> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Child orgs

> Open an account for each of your customers. Your customer owns the money. You use the API for your customer.

A **Child org** is an account that you open for one of your customers. Your
customer can be a person or a business. The money in a Child org belongs to
your customer, not to you. Your customer does not use Hermes. Your customer
uses your product, and you use the API for your customer.

A Child org is a full org. It has its own balances, its own USD bank
details, its own deposit addresses, and its own USD beneficiaries. It does
not have API keys, users, or webhook endpoints. Only you, the parent, can
use it.

> [!NOTE]
>
> Jenzy must let your org have Child orgs. If Jenzy did not,
> `POST /v2/child-orgs` gets `403` with the code `forbidden`. To get Child
> orgs, speak to Jenzy.

## How a Child org opens

1. **Create** the Child org with `POST /v2/child-orgs`. Send the details of
   your customer. The Child org starts `incomplete`.
2. **Upload the documents** that `requirements` lists, with
   `POST /v2/child-orgs/{id}/documents`.
3. **Show the terms** at `terms_url` to your customer. When your customer
   accepts them, send the value with `POST /v2/child-orgs/{id}/terms`.
4. When you owe nothing, the **review** starts. The status becomes
   `in_review`.
5. The review approves the Child org (`active`), asks for more
   (`action_required`), or refuses it (`rejected`).

Jenzy does not do the review and does not promise a time for it. You get a
`child_org.updated` event each time the status, the `requirements`, or the
`capabilities` change.

## Create a Child org

Send `type` and one object for that type. You can also send `reference`.
It is your own id for the customer. It must be unique among your Child
orgs.

This request does not use an `Idempotency-Key`. Send a `reference` to make
a retry safe: a second request with the same `reference` gets `409` with
the code `conflict`.

> [tab] Person
>
> ```bash theme={null}
> curl -X POST https://api.jenzy.com/v2/child-orgs \
>   -H "Authorization: Bearer jz_live_…" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "individual",
>     "reference": "cust_8812",
>     "individual": {
>       "first_name": "Freya",
>       "last_name": "Krause",
>       "date_of_birth": "1982-03-24",
>       "email": "freya.krause@example.com",
>       "phone": "+4922155501000",
>       "country_of_residence": "DE",
>       "nationality": "DE",
>       "address": {
>         "street_line_1": "Heidestrasse 19",
>         "city": "Koeln",
>         "subdivision_code": "DE-NW",
>         "postal_code": "51247",
>         "country": "DE"
>       },
>       "identity_document": {
>         "type": "passport",
>         "number": "C01X00T47",
>         "country": "DE",
>         "issue_date": "2020-05-01",
>         "expiry_date": "2030-04-30"
>       },
>       "financial_profile": {
>         "employment_status": "employed",
>         "occupation_id": 533,
>         "purpose_id": 3,
>         "source_of_fund_ids": [1],
>         "monthly_volume_usd": 5000
>       }
>     }
>   }'
> ```

> [tab] Business
>
> ```bash theme={null}
> curl -X POST https://api.jenzy.com/v2/child-orgs \
>   -H "Authorization: Bearer jz_live_…" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "business",
>     "reference": "cust_9034",
>     "business": {
>       "legal_name": "Meridian Cargo Ltd",
>       "description": "Freight forwarding between the UK and East Africa.",
>       "entity_type": "corporation",
>       "email": "accounts@meridiancargo.co.uk",
>       "phone": "+442079460187",
>       "incorporation_date": "2019-04-17",
>       "country_of_incorporation": "GB",
>       "registration_number": "88888888",
>       "industry_codes": ["488510"],
>       "address": {
>         "street_line_1": "11 Harbor Lane",
>         "city": "London",
>         "subdivision_code": "GB-LND",
>         "postal_code": "EC1A 1BB",
>         "country": "GB"
>       },
>       "financial_profile": {
>         "purpose_id": 11,
>         "source_of_fund_ids": [21],
>         "source_of_wealth_ids": [1],
>         "estimated_annual_revenue_usd": 1000000,
>         "expected_monthly_deposits_usd": 50000,
>         "expected_monthly_withdrawals_usd": 50000,
>         "expected_transaction_value_usd": 5000,
>         "expected_monthly_transaction_count": 10,
>         "third_party_fund_usage": false
>       },
>       "associated_parties": [
>         {
>           "first_name": "Freya",
>           "last_name": "Krause",
>           "date_of_birth": "1982-03-24",
>           "email": "freya.krause@example.com",
>           "phone": "+4922155501000",
>           "country_of_residence": "DE",
>           "nationality": "DE",
>           "address": {
>             "street_line_1": "Heidestrasse 19",
>             "city": "Koeln",
>             "subdivision_code": "DE-NW",
>             "postal_code": "51247",
>             "country": "DE"
>           },
>           "identity_document": {
>             "type": "passport",
>             "number": "C01X00T47",
>             "country": "DE",
>             "issue_date": "2020-05-01",
>             "expiry_date": "2030-04-30"
>           },
>           "roles": ["shareholder", "ubo"],
>           "ownership": {
>             "percentage": 100,
>             "has_control": true,
>             "is_signer": true,
>             "is_director": true
>           }
>         }
>       ]
>     }
>   }'
> ```

The answer is `201` and the Child org. Hermes checks each field first. A bad
field gets `400` with the code `validation_error`. The message names the
field.

Some rules for the fields:

* A country is an ISO 3166-1 alpha-2 code, for example `DE`.
  `subdivision_code` is an ISO 3166-2 code that starts with the country, for
  example `DE-NW`.
* A date is `YYYY-MM-DD`. A phone number is in E.164 form, with the `+`.
* `identity_document.type` is `passport`, `national_id`, `drivers_license`,
  or `residence_permit`. You upload the file later, with the same `type`.
* A business has one or more `associated_parties`: its owners, directors,
  and signers. Each party has its own email.
* `industry_codes` are 6-digit NAICS 2022 codes. See
  [Industries that Jenzy does not serve](#industries-that-jenzy-does-not-serve).
* `tax_id` is optional. It has `country`, `type`, and `number`.

### The lists

Some fields take a value from a fixed list. Get the lists with
`GET /v2/lists`:

```bash theme={null}
curl https://api.jenzy.com/v2/lists \
  -H "Authorization: Bearer jz_live_…"
```

```json theme={null}
{
  "occupations": [{ "id": 533, "name": "Teller" }],
  "employment_statuses": ["employed", "self_employed", "retired", "student", "unemployed"],
  "entity_types": ["limited_liability_company", "corporation", "…"],
  "party_roles": ["shareholder", "ubo"],
  "purposes": { "individual": [{ "id": 1, "name": "…" }], "business": [{ "id": 10, "name": "Payroll" }] },
  "sources_of_funds": { "individual": [{ "id": 1, "name": "…" }], "business": [{ "id": 13, "name": "…" }] },
  "sources_of_wealth": { "business": [{ "id": 1, "name": "…" }] },
  "prohibited_industry_codes": ["713210", "…"]
}
```

| Field | List |
| - | - |
| `financial_profile.occupation_id` | `occupations` |
| `financial_profile.employment_status` | `employment_statuses` |
| `financial_profile.purpose_id` | `purposes.individual` or `purposes.business` |
| `financial_profile.source_of_fund_ids` | `sources_of_funds.individual` or `sources_of_funds.business` |
| `financial_profile.source_of_wealth_ids` | `sources_of_wealth.business` |
| `business.entity_type` | `entity_types` |
| `associated_parties[].roles` | `party_roles` |

A value that is not in its list gets `400` with the code
`validation_error`. The lists do not change often. You can keep a copy.

### Industries that Jenzy does not serve

Jenzy does not open a Child org for a business in these industries:

* Bearer share corporations and shell companies
* Pornography, escort services, and the sale or advertising of sexual
  services
* Bonded warehouses
* Cash intensive businesses, for example the import of used vehicles or
  vehicle parts, laundromats, and pawn shops
* Charities without a registration, and crowdfunding
* Convenience stores
* Defence and weapons, and nuclear or military energy
* Development aid and embassies
* Gambling and gaming
* Lobbying, pressure groups, and think tanks
* Sanctioned businesses
* Cannabis and cannabis products or services

`industry_codes` are 6-digit NAICS 2022 codes. A code in
`prohibited_industry_codes` gets `422` with the code `prohibited_industry`.
Hermes does not keep the Child org. Jenzy can also refuse or close a Child
org in one of these industries after the review.

## The Child org resource

```json theme={null}
{
  "id": "3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10",
  "type": "individual",
  "display_name": "Freya Krause",
  "reference": "cust_8812",
  "status": "incomplete",
  "requirements": [
    {
      "party_id": null,
      "field": null,
      "document_category": "identifying_documents",
      "document_types": ["passport"],
      "reason": "missing"
    },
    {
      "party_id": null,
      "field": "terms_value",
      "document_category": null,
      "document_types": [],
      "reason": "missing"
    }
  ],
  "capabilities": { "usd_collections": "pending", "usd_payouts": "pending" },
  "associated_parties": [],
  "terms_url": "https://…",
  "created_at": "2026-11-11T09:14:02.000Z"
}
```

Read your Child orgs with `GET /v2/child-orgs`, newest first, and one Child
org with `GET /v2/child-orgs/{id}`.

### Statuses

| `status` | Meaning | What to do |
| - | - | - |
| `incomplete` | You owe some items before the review. `requirements` lists them. | Upload the documents and send the terms value. |
| `in_review` | You owe nothing. The review continues. | Wait for `child_org.updated`. |
| `action_required` | The review needs more from you. `requirements` lists it. | [Answer the request](#answer-a-request-for-information). |
| `active` | The review approved the Child org. It can move money. | Use it with the `Hermes-Org` header. |
| `rejected` | The review refused the Child org. This status is final. | To try again, create a new Child org. |
| `suspended` | Jenzy suspended the Child org, or your org. | Speak to Jenzy. |

An `incomplete` Child org does not expire. A `rejected` Child org stays in
your list.

### Requirements

Each item in `requirements` is one thing that you owe. It is for the Child
org, or for one associated party. For the Child org, `party_id` is `null`.
For a party, `party_id` is the `id` of the party.

* **A document** has a `document_category` and the `document_types` that
  are correct for it. One file of one of these types is enough.
  `field` is `null`.
* **A detail** has a `field`, for example `terms_value` or
  `identity_document.expiry_date`. `document_category` is `null`.

`reason` is `missing`, `expired`, or `invalid`.

An `active` Child org can also get a request after the approval. Then
`requirements` lists it, and the status stays `active`.

### Capabilities

`capabilities` tells you what the Child org can do in USD. Each value is
`pending`, `active`, or `unavailable`.

| Capability | `active` means |
| - | - |
| `usd_collections` | The Child org has USD bank details. A payer can send USD to them. |
| `usd_payouts` | The Child org can send USD payouts. |

A check by the bank can continue after the approval. Until it ends, a
capability stays `pending`. When the Child org is `rejected`, each
capability is `unavailable`.

## Upload documents

Send each document as `multipart/form-data`:

| Part | What to send |
| - | - |
| `file` | The file. A PDF, a JPEG, or a PNG, of 5 MB or less. |
| `type` | One of the `document_types` from `requirements`. |
| `side` | `front` or `back`, for a type that has two sides. `national_id`, `drivers_license`, and `residence_permit` have two sides. |
| `party_id` | The `id` of the associated party, for a document of a party. |

```bash theme={null}
curl -X POST https://api.jenzy.com/v2/child-orgs/3f1c2a9e-…/documents \
  -H "Authorization: Bearer jz_live_…" \
  -F "file=@passport.pdf" \
  -F "type=passport"
```

The answer is `201` and the document. A file that is too large gets `413`
with the code `payload_too_large`. A file that is not a PDF, a JPEG, or a
PNG gets `415` with the code `unsupported_media_type`.

## Send the terms value

You must show the terms page at `terms_url` to your customer. Your customer
must accept the terms. You cannot accept them for your customer.

When your customer accepts, the page gives a `tos_policies_value`. Send it
as `terms_value`:

```bash theme={null}
curl -X POST https://api.jenzy.com/v2/child-orgs/3f1c2a9e-…/terms \
  -H "Authorization: Bearer jz_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "terms_value": "…" }'
```

The answer is the Child org. When you owe nothing more, its status is
`in_review`. After you send the value, `terms_url` is `null`.

## Answer a request for information

When the review needs more, the status is `action_required`, or
`requirements` lists new items on an `active` Child org. Do these steps:

1. Upload each document that `requirements` lists, with
   `POST /v2/child-orgs/{id}/documents`.
2. Send `POST /v2/child-orgs/{id}/information` with the details that
   `requirements` lists:
   * `identity_documents`: a new identity document, when `requirements`
     lists an `identity_document.*` field. Each item has `party_id`, `type`,
     `number`, `country`, `issue_date`, and `expiry_date`. Upload the file
     with the same `type` first.
   * `terms_value`: when `requirements` lists `terms_value`.

```bash theme={null}
curl -X POST https://api.jenzy.com/v2/child-orgs/3f1c2a9e-…/information \
  -H "Authorization: Bearer jz_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_documents": [
      {
        "party_id": null,
        "type": "passport",
        "number": "C01X00T48",
        "country": "DE",
        "issue_date": "2025-06-01",
        "expiry_date": "2035-05-31"
      }
    ]
  }'
```

The answer is the Child org, with its new status. If an item that
`requirements` lists has no answer, the request gets `400` with the code
`validation_error`. The message names the item. If the review asks for nothing,
the request gets `409` with the code `conflict`.

Only Jenzy can answer some requests. For these, the request gets `409`
with the code `conflict`. Speak to Jenzy.

## Use the API for a Child org

To make a `/v2` request for a Child org, send its `id` in the `Hermes-Org`
header. Use your own API key.

```bash theme={null}
curl https://api.jenzy.com/v2/balances \
  -H "Authorization: Bearer jz_live_…" \
  -H "Hermes-Org: 3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10"
```

* With the header, the request is for the Child org: its balances, its
  collections, its payouts, and its beneficiaries. Without the header, the
  request is for your org.
* The header works only on `/v2`, and only when the Child org is `active`.
* An `id` that is not one of your Child orgs gets `404` with the code
  `not_found`. A Child org that is not `active` yet also gets `404`.
* A `suspended` Child org gets `403` with the code `forbidden`.
* Orders are not available for a Child org. An order request with the
  header gets `404`.
* An `Idempotency-Key` is unique for each org. The same key on your org and
  on a Child org makes two different requests.

### What a Child org gets from you

* **Prices.** A Child org pays your prices. When Jenzy changes your prices,
  the change applies to each Child org at once. Jenzy does not add a margin
  for you. You charge your customer outside Hermes.
* **Assets.** A Child org can use the stablecoins and the USD that Jenzy
  enables for your org. `capabilities` also controls USD for the Child org.
* **Suspension.** When Jenzy suspends your org, each Child org is also
  `suspended`. When Jenzy removes the suspension, the Child orgs continue.

### No money moves between orgs

Hermes does not move money between your org and a Child org, or between
two Child orgs. Each Child org owns its money. To move the stablecoins of a
Child org, send a `wallet` payout from the Child org to an address. The
address can be a deposit address of your org. See [Payouts](https://docs.jenzy.com/v2/payouts.md).

Each Child org registers its own [USD beneficiaries](https://docs.jenzy.com/v2/beneficiaries.md).
A beneficiary of one org cannot get a payout from a different org.

## Webhooks

The events of a Child org go to your webhook endpoint. Each event of a
Child org has `org_id`. It is the `id` of the Child org, the same value as
the `Hermes-Org` header. The events of your own org do not have `org_id`.

```json theme={null}
{
  "id": "9c2e4f1a-7b3d-4e5f-8a6b-1c2d3e4f5a6b",
  "event_type": "child_org.updated",
  "api_version": "v2",
  "org_id": "3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10",
  "created_at": "2026-11-11T09:20:44.000Z",
  "data": { "...": "the Child org, as GET /v2/child-orgs/{id} shows it" }
}
```

Hermes sends `child_org.updated` when the `status`, the `requirements`, or
the `capabilities` of a Child org change. There is no event when you
create a Child org. The answer to your `POST` gives the Child org.

## Test in the sandbox

In the sandbox, you select the result of the review. Use the last name of a
person, or the `legal_name` of a business. See
[Sandbox → Child orgs](https://docs.jenzy.com/v2/sandbox.md#child-orgs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.