> ## 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.

# Create a Child org

> Open a Child org for your customer, an individual or a business. Only for an organization that Jenzy allows to have Child orgs. The Child org starts `incomplete`: upload the documents in `requirements`, show `terms_url` to your customer and send `terms_value`. Then the review starts.



## OpenAPI

````yaml /v2/openapi.json post /child-orgs
openapi: 3.1.0
info:
  title: Jenzy Hermes Multi-asset API
  version: 2.0.0
  description: >-
    Hold and pay out across the assets enabled for your organization. Every
    amount is an exact decimal string beside an `asset` field. Authenticate with
    the same `jz_live_…` API key as `/v1`.
servers:
  - url: https://api.jenzy.com/v2
    description: Production
security: []
paths:
  /child-orgs:
    post:
      summary: Create a Child org
      description: >-
        Open a Child org for your customer, an individual or a business. Only
        for an organization that Jenzy allows to have Child orgs. The Child org
        starts `incomplete`: upload the documents in `requirements`, show
        `terms_url` to your customer and send `terms_value`. Then the review
        starts.
      parameters:
        - $ref: '#/components/parameters/HermesOrg'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChildOrgCreate'
      responses:
        '201':
          description: Created, `incomplete`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChildOrg'
        '400':
          description: '`validation_error`: a field fails its check; the message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            `forbidden`: your organization may not have Child orgs. Also the
            access codes of every `/v2` route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: '`conflict`: you already have a Child org with this `reference`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: >-
            `prohibited_industry`: an `industry_codes` entry is an industry
            Jenzy does not serve; the message names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: The `/v2` shutter is closed — check `GET /v2/ping`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    HermesOrg:
      name: HERMES-ORG
      in: header
      required: false
      description: >-
        The id of one of your Child orgs. The call then acts on that Child org,
        not on your organization. If you do not send it, the call acts on your
        organization. An id that is not one of your Child orgs gives `404`.
      schema:
        type: string
        format: uuid
        example: 3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10
  schemas:
    ChildOrgCreate:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - individual
            reference:
              type: string
              minLength: 1
              maxLength: 128
              description: Your own id for this customer. Unique among your Child orgs.
              example: cust_8812
            individual:
              type: object
              properties:
                first_name:
                  type: string
                  minLength: 1
                last_name:
                  type: string
                  minLength: 1
                date_of_birth:
                  type: string
                  format: date
                  description: '`YYYY-MM-DD`.'
                  example: '1982-03-24'
                email:
                  type: string
                  format: email
                phone:
                  type: string
                  description: E.164 with the leading `+`.
                  example: '+4922155501000'
                country_of_residence:
                  type: string
                  description: ISO 3166-1 alpha-2.
                  example: DE
                nationality:
                  type: string
                  description: ISO 3166-1 alpha-2.
                  example: DE
                tax_id:
                  type: object
                  properties:
                    country:
                      type: string
                      description: ISO 3166-1 alpha-2.
                      example: DE
                    type:
                      type: string
                      minLength: 1
                      example: STEUER_ID
                    number:
                      type: string
                      minLength: 1
                  required:
                    - country
                    - type
                    - number
                  additionalProperties: false
                address:
                  type: object
                  properties:
                    street_line_1:
                      type: string
                      minLength: 1
                    street_line_2:
                      type: string
                      minLength: 1
                    city:
                      type: string
                      minLength: 1
                    subdivision_code:
                      type: string
                      description: >-
                        ISO 3166-2 subdivision whose prefix is `country`
                        (`DE-NW`).
                      example: DE-NW
                    postal_code:
                      type: string
                      minLength: 1
                    country:
                      type: string
                      description: ISO 3166-1 alpha-2.
                      example: DE
                  required:
                    - street_line_1
                    - city
                    - subdivision_code
                    - postal_code
                    - country
                  additionalProperties: false
                identity_document:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - passport
                        - national_id
                        - drivers_license
                        - residence_permit
                      description: >-
                        Upload this type later. `national_id`, `drivers_license`
                        and `residence_permit` need a front and a back.
                    number:
                      type: string
                      minLength: 1
                    country:
                      type: string
                      description: ISO 3166-1 alpha-2.
                      example: DE
                    issue_date:
                      type: string
                      format: date
                      description: '`YYYY-MM-DD`.'
                      example: '1982-03-24'
                    expiry_date:
                      type: string
                      format: date
                      description: '`YYYY-MM-DD`.'
                      example: '1982-03-24'
                  required:
                    - type
                    - number
                    - country
                    - issue_date
                    - expiry_date
                  additionalProperties: false
                gender:
                  type: string
                  enum:
                    - female
                    - male
                financial_profile:
                  type: object
                  properties:
                    employment_status:
                      type: string
                      enum:
                        - employed
                        - self_employed
                        - retired
                        - student
                        - unemployed
                    occupation_id:
                      type: integer
                      exclusiveMinimum: 0
                    purpose_id:
                      type: integer
                      exclusiveMinimum: 0
                    purpose_remarks:
                      type: string
                      minLength: 1
                    source_of_funds_description:
                      type: string
                      minLength: 1
                    source_of_fund_ids:
                      type: array
                      items:
                        type: integer
                        exclusiveMinimum: 0
                      minItems: 1
                    monthly_volume_usd:
                      type: integer
                      minimum: 0
                  required:
                    - employment_status
                    - occupation_id
                    - purpose_id
                    - source_of_fund_ids
                    - monthly_volume_usd
                  additionalProperties: false
              required:
                - first_name
                - last_name
                - date_of_birth
                - email
                - phone
                - country_of_residence
                - nationality
                - address
                - identity_document
                - financial_profile
              additionalProperties: false
          required:
            - type
            - individual
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - business
            reference:
              type: string
              minLength: 1
              maxLength: 128
              description: Your own id for this customer. Unique among your Child orgs.
              example: cust_8812
            business:
              type: object
              properties:
                legal_name:
                  type: string
                  minLength: 1
                trade_name:
                  type: string
                  minLength: 1
                description:
                  type: string
                  minLength: 1
                entity_type:
                  type: string
                  enum:
                    - limited_liability_company
                    - publicly_listed_company
                    - sole_proprietor
                    - partnership
                    - corporation
                    - nonprofit_organization
                    - public_agency_or_authority
                email:
                  type: string
                  format: email
                phone:
                  type: string
                incorporation_date:
                  type: string
                  format: date
                  description: '`YYYY-MM-DD`.'
                  example: '1982-03-24'
                country_of_incorporation:
                  type: string
                  description: ISO 3166-1 alpha-2.
                  example: DE
                registration_number:
                  type: string
                  minLength: 1
                tax_id:
                  type: object
                  properties:
                    country:
                      type: string
                      description: ISO 3166-1 alpha-2.
                      example: DE
                    type:
                      type: string
                      minLength: 1
                      example: STEUER_ID
                    number:
                      type: string
                      minLength: 1
                  required:
                    - country
                    - type
                    - number
                  additionalProperties: false
                websites:
                  type: array
                  items:
                    type: string
                    format: uri
                industry_codes:
                  type: array
                  items:
                    type: string
                    pattern: ^\d{6}$
                  minItems: 1
                  description: >-
                    6-digit NAICS 2022 codes. A code in
                    `prohibited_industry_codes` of `GET /v2/lists` gets `422
                    prohibited_industry`.
                  example:
                    - '488510'
                address:
                  type: object
                  properties:
                    street_line_1:
                      type: string
                      minLength: 1
                    street_line_2:
                      type: string
                      minLength: 1
                    city:
                      type: string
                      minLength: 1
                    subdivision_code:
                      type: string
                      description: >-
                        ISO 3166-2 subdivision whose prefix is `country`
                        (`DE-NW`).
                      example: DE-NW
                    postal_code:
                      type: string
                      minLength: 1
                    country:
                      type: string
                      description: ISO 3166-1 alpha-2.
                      example: DE
                  required:
                    - street_line_1
                    - city
                    - subdivision_code
                    - postal_code
                    - country
                  additionalProperties: false
                financial_profile:
                  type: object
                  properties:
                    purpose_id:
                      type: integer
                      exclusiveMinimum: 0
                    source_of_fund_ids:
                      type: array
                      items:
                        type: integer
                        exclusiveMinimum: 0
                      minItems: 1
                    source_of_wealth_ids:
                      type: array
                      items:
                        type: integer
                        exclusiveMinimum: 0
                      minItems: 1
                    estimated_annual_revenue_usd:
                      type: integer
                      minimum: 0
                    expected_monthly_deposits_usd:
                      type: integer
                      minimum: 0
                    expected_monthly_withdrawals_usd:
                      type: integer
                      minimum: 0
                    expected_transaction_value_usd:
                      type: integer
                      minimum: 0
                    expected_monthly_transaction_count:
                      type: integer
                      minimum: 0
                    third_party_fund_usage:
                      type: boolean
                  required:
                    - purpose_id
                    - source_of_fund_ids
                    - source_of_wealth_ids
                    - estimated_annual_revenue_usd
                    - expected_monthly_deposits_usd
                    - expected_monthly_withdrawals_usd
                    - expected_transaction_value_usd
                    - expected_monthly_transaction_count
                    - third_party_fund_usage
                  additionalProperties: false
                associated_parties:
                  type: array
                  items:
                    type: object
                    properties:
                      first_name:
                        type: string
                        minLength: 1
                      last_name:
                        type: string
                        minLength: 1
                      date_of_birth:
                        type: string
                        format: date
                        description: '`YYYY-MM-DD`.'
                        example: '1982-03-24'
                      email:
                        type: string
                        format: email
                      phone:
                        type: string
                        description: E.164 with the leading `+`.
                        example: '+4922155501000'
                      country_of_residence:
                        type: string
                        description: ISO 3166-1 alpha-2.
                        example: DE
                      nationality:
                        type: string
                        description: ISO 3166-1 alpha-2.
                        example: DE
                      tax_id:
                        type: object
                        properties:
                          country:
                            type: string
                            description: ISO 3166-1 alpha-2.
                            example: DE
                          type:
                            type: string
                            minLength: 1
                            example: STEUER_ID
                          number:
                            type: string
                            minLength: 1
                        required:
                          - country
                          - type
                          - number
                        additionalProperties: false
                      address:
                        type: object
                        properties:
                          street_line_1:
                            type: string
                            minLength: 1
                          street_line_2:
                            type: string
                            minLength: 1
                          city:
                            type: string
                            minLength: 1
                          subdivision_code:
                            type: string
                            description: >-
                              ISO 3166-2 subdivision whose prefix is `country`
                              (`DE-NW`).
                            example: DE-NW
                          postal_code:
                            type: string
                            minLength: 1
                          country:
                            type: string
                            description: ISO 3166-1 alpha-2.
                            example: DE
                        required:
                          - street_line_1
                          - city
                          - subdivision_code
                          - postal_code
                          - country
                        additionalProperties: false
                      identity_document:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - passport
                              - national_id
                              - drivers_license
                              - residence_permit
                            description: >-
                              Upload this type later. `national_id`,
                              `drivers_license` and `residence_permit` need a
                              front and a back.
                          number:
                            type: string
                            minLength: 1
                          country:
                            type: string
                            description: ISO 3166-1 alpha-2.
                            example: DE
                          issue_date:
                            type: string
                            format: date
                            description: '`YYYY-MM-DD`.'
                            example: '1982-03-24'
                          expiry_date:
                            type: string
                            format: date
                            description: '`YYYY-MM-DD`.'
                            example: '1982-03-24'
                        required:
                          - type
                          - number
                          - country
                          - issue_date
                          - expiry_date
                        additionalProperties: false
                      roles:
                        type: array
                        items:
                          type: string
                          enum:
                            - shareholder
                            - ubo
                        minItems: 1
                        example:
                          - shareholder
                          - ubo
                      ownership:
                        type: object
                        properties:
                          designation:
                            type: string
                            minLength: 1
                          percentage:
                            type: number
                            minimum: 0
                            maximum: 100
                          relationship_establishment_date:
                            type: string
                            format: date
                            description: '`YYYY-MM-DD`.'
                            example: '1982-03-24'
                          has_control:
                            type: boolean
                          is_signer:
                            type: boolean
                          is_director:
                            type: boolean
                        required:
                          - percentage
                          - has_control
                          - is_signer
                          - is_director
                        additionalProperties: false
                    required:
                      - first_name
                      - last_name
                      - date_of_birth
                      - email
                      - phone
                      - country_of_residence
                      - nationality
                      - address
                      - identity_document
                      - roles
                      - ownership
                    additionalProperties: false
                  minItems: 1
              required:
                - legal_name
                - description
                - entity_type
                - email
                - phone
                - incorporation_date
                - country_of_incorporation
                - registration_number
                - industry_codes
                - address
                - financial_profile
                - associated_parties
              additionalProperties: false
          required:
            - type
            - business
          additionalProperties: false
    ChildOrg:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The Child org id.
        type:
          type: string
          enum:
            - individual
            - business
        display_name:
          type: string
        reference:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - incomplete
            - in_review
            - action_required
            - active
            - rejected
            - suspended
          description: >-
            `incomplete`: `requirements` lists what you still owe before review.
            `in_review`: nothing is owed; the review is in progress.
            `action_required`: the review needs more from you; `requirements`
            lists it, and you send it with `POST
            /v2/child-orgs/{id}/information`. `active`: approved; the Child org
            can transact. `requirements` can list a request after approval; the
            status stays `active`. `rejected`: final; to try again, create a new
            Child org. `suspended`: the Child org or your organization is
            suspended.
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/ChildOrgRequirement'
        capabilities:
          type: object
          properties:
            usd_collections:
              type: string
              enum:
                - pending
                - active
                - unavailable
            usd_payouts:
              type: string
              enum:
                - pending
                - active
                - unavailable
          required:
            - usd_collections
            - usd_payouts
        associated_parties:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
            required:
              - id
          description: >-
            A business’s associated parties, in the order you sent them. Name a
            party’s `id` when you upload its documents.
        terms_url:
          type:
            - string
            - 'null'
          description: >-
            The terms page to show your customer. After your customer accepts,
            send `terms_value`. Null after you send it.
        created_at:
          type: string
          format: date-time
      required:
        - id
        - type
        - display_name
        - reference
        - status
        - requirements
        - capabilities
        - associated_parties
        - terms_url
        - created_at
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
                - unauthorized
                - forbidden
                - not_found
                - conflict
                - rate_limited
                - internal_error
                - unknown_institution
                - invalid_mobile_number
                - invalid_account_number
                - mobile_number_institution_mismatch
                - service_unavailable
                - sandbox_only
                - insufficient_funds
                - rail_disabled
                - amount_limit_exceeded
                - org_limit_exceeded
                - service_incident
                - service_maintenance
                - onboarding_incomplete
                - access_suspended
                - corridor_not_enabled
                - unsupported_pair
                - invalid_wallet_address
                - rate_unavailable
                - quote_expired
                - quote_used
                - limit_exceeded
                - amount_below_minimum
                - unsupported_asset
                - unsupported_network
                - unsupported_media_type
                - payload_too_large
                - client_ref_used
                - beneficiary_required
                - beneficiary_not_allowed
                - proof_not_expected
                - invalid_beneficiary
                - beneficiary_exists
                - beneficiary_not_active
                - invoice_required
                - prohibited_industry
              description: >-
                Stable identifier a client may branch on — never renamed or
                removed.
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
    ChildOrgRequirement:
      type: object
      properties:
        party_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The associated party that owes it; null for the Child org itself.
        field:
          type:
            - string
            - 'null'
          description: >-
            A detail that is owed, e.g. `terms_value` or
            `identity_document.expiry_date`. Null for a document.
          example: terms_value
        document_category:
          type:
            - string
            - 'null'
          description: The category of document that is owed. Null for a detail.
          example: identifying_documents
        document_types:
          type: array
          items:
            type: string
          description: 'The document `type`s that satisfy it: one of them is enough.'
          example:
            - passport
            - national_id
        reason:
          type: string
          enum:
            - missing
            - expired
            - invalid
      required:
        - party_id
        - field
        - document_category
        - document_types
        - reason
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Your Jenzy API key: `Authorization: Bearer jz_live_…`'

````

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