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

# Register a USD beneficiary

> Register a business’s US or SWIFT bank account to pay with USD payouts. It is checked before it can be paid: it starts `pending`, and only an `active` one is payable. It cannot be changed: new bank details are a new beneficiary. Send the same bank details and body again and you get the existing beneficiary (200). No `Idempotency-Key`. USD beneficiaries are for USD payouts only. Every other asset pays an inline `destination`.



## OpenAPI

````yaml /v2/openapi.json post /beneficiaries
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:
  /beneficiaries:
    post:
      summary: Register a USD beneficiary
      description: >-
        Register a business’s US or SWIFT bank account to pay with USD payouts.
        It is checked before it can be paid: it starts `pending`, and only an
        `active` one is payable. It cannot be changed: new bank details are a
        new beneficiary. Send the same bank details and body again and you get
        the existing beneficiary (200). No `Idempotency-Key`. USD beneficiaries
        are for USD payouts only. Every other asset pays an inline
        `destination`.
      parameters:
        - $ref: '#/components/parameters/HermesOrg'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsdBeneficiaryCreate'
      responses:
        '200':
          description: >-
            These bank details are already registered with this body: the
            existing one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsdBeneficiary'
        '201':
          description: >-
            Registered. `status` is normally `pending`; it can already be
            `rejected` with `recipient_account_invalid` when the bank details
            are refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsdBeneficiary'
        '400':
          description: The body is not JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            `corridor_not_enabled`: USD payouts are not enabled for your
            organization. Also the access codes above.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: >-
            `beneficiary_exists`: these bank details are registered with a
            different body; the message names the existing id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: >-
            `invalid_beneficiary`: a field fails its check; 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:
    UsdBeneficiaryCreate:
      type: object
      properties:
        holder:
          oneOf:
            - $ref: '#/components/schemas/UsdBeneficiaryBusinessHolder'
            - $ref: '#/components/schemas/UsdBeneficiaryIndividualHolder'
          discriminator:
            propertyName: type
            mapping:
              business: '#/components/schemas/UsdBeneficiaryBusinessHolder'
              individual: '#/components/schemas/UsdBeneficiaryIndividualHolder'
        holder_address:
          type: object
          properties:
            street_line_1:
              type: string
              minLength: 1
            city:
              type: string
              minLength: 1
            state:
              type: string
              description: ISO 3166-2 subdivision whose prefix is `country` (`US-NY`).
              example: US-NY
            postcode:
              type: string
              minLength: 1
            country:
              type: string
              description: ISO 3166-1 alpha-2 (`US`).
              example: US
          required:
            - street_line_1
            - city
            - state
            - postcode
            - country
          additionalProperties: false
        bank:
          type: object
          properties:
            name:
              type: string
              minLength: 1
              example: Column NA
            account_number:
              type: string
              pattern: ^\d{4,17}$
              example: '787212236285345'
            account_type:
              type: string
              enum:
                - checking
                - savings
            address:
              type: object
              properties:
                street_line_1:
                  type: string
                  minLength: 1
                city:
                  type: string
                  minLength: 1
                state:
                  type: string
                  description: ISO 3166-2 subdivision whose prefix is `country` (`US-NY`).
                  example: US-NY
                postcode:
                  type: string
                  minLength: 1
                country:
                  type: string
                  description: ISO 3166-1 alpha-2 (`US`).
                  example: US
              required:
                - street_line_1
                - city
                - state
                - postcode
                - country
              additionalProperties: false
          required:
            - name
            - account_number
            - account_type
            - address
          additionalProperties: false
        rail:
          type: string
          enum:
            - fedwire
            - swift
          description: 'How the USD is sent: `fedwire` (US banks) or `swift`.'
        routing_number:
          type: string
          description: '`fedwire`: the 9-digit ABA routing number. `swift`: the bank’s BIC.'
          example: '121145349'
        intermediary_routing_number:
          type: string
          description: >-
            Required for `swift`, refused for `fedwire`: the intermediary bank’s
            ABA routing number or BIC.
        counter_party:
          type: string
          enum:
            - first_party
            - third_party
          description: >-
            `first_party`: an account of your own organization. `third_party`:
            anyone else.
        relationship:
          type: string
          enum:
            - supplier
            - vendor
            - service_provider
            - merchant
            - contractor
            - customer
            - subsidiary
            - parent_company
            - affiliate_business
            - bank_account
            - employee
            - freelancer
            - gig_worker
            - affiliate
            - family_member
            - friend
            - self
          description: What the holder is to your organization.
        purpose:
          type: string
          enum:
            - goods
            - services
            - freight
            - intercompany
            - family_support
            - income
            - education
            - donation
            - investment
            - own_account
          description: >-
            Why your organization pays this holder. A `business` holder takes
            `goods`, `services`, `freight` or `intercompany`. An `individual`
            holder takes `family_support`, `goods`, `services`, `income`,
            `education`, `donation`, `investment` or `own_account`.
      required:
        - holder
        - holder_address
        - bank
        - rail
        - routing_number
        - counter_party
        - relationship
        - purpose
      additionalProperties: false
    UsdBeneficiary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Name it in a USD payout’s `destination.beneficiary_id`.
        asset:
          type: string
          minLength: 1
          description: '`USD`: beneficiaries are for USD payouts only.'
          example: USD
        status:
          type: string
          enum:
            - pending
            - active
            - rejected
            - inactive
          description: >-
            `pending`: being checked, not payable yet. `active`: payable.
            `rejected`: final; these bank details cannot be registered again.
            `inactive`: not payable now; it may become `active` again.
        holder:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - business
                name:
                  type: string
                email:
                  type: string
                phone:
                  type: string
              required:
                - type
                - name
                - email
                - phone
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - individual
                first_name:
                  type: string
                last_name:
                  type: string
                email:
                  type: string
                phone:
                  type: string
                occupation_id:
                  type: integer
              required:
                - type
                - first_name
                - last_name
                - email
                - phone
                - occupation_id
        holder_address:
          type: object
          properties:
            street_line_1:
              type: string
            city:
              type: string
            state:
              type: string
            postcode:
              type: string
            country:
              type: string
          required:
            - street_line_1
            - city
            - state
            - postcode
            - country
        bank:
          type: object
          properties:
            name:
              type: string
            account_number:
              type: string
            account_type:
              type: string
              enum:
                - checking
                - savings
            address:
              type: object
              properties:
                street_line_1:
                  type: string
                city:
                  type: string
                state:
                  type: string
                postcode:
                  type: string
                country:
                  type: string
              required:
                - street_line_1
                - city
                - state
                - postcode
                - country
          required:
            - name
            - account_number
            - account_type
            - address
        rail:
          type: string
          example: fedwire
        routing_number:
          type: string
        intermediary_routing_number:
          type:
            - string
            - 'null'
        counter_party:
          type: string
          example: third_party
        relationship:
          type: string
          example: supplier
        purpose:
          type: string
          example: freight
        failure:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              enum:
                - recipient_account_invalid
                - declined
                - provider_unavailable
                - temporarily_unavailable
            message:
              type: string
          required:
            - code
            - message
          description: >-
            Set only when `status` is `rejected`: `recipient_account_invalid`
            (the bank details were refused) or `declined`.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - asset
        - status
        - holder
        - holder_address
        - bank
        - rail
        - routing_number
        - intermediary_routing_number
        - counter_party
        - relationship
        - purpose
        - failure
        - created_at
        - updated_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
    UsdBeneficiaryBusinessHolder:
      type: object
      properties:
        type:
          type: string
          enum:
            - business
        name:
          type: string
          minLength: 1
          example: Meridian Cargo Solutions LLC
        email:
          type: string
          format: email
        phone:
          type: string
          description: E.164 with the leading `+`.
          example: '+17189042371'
      required:
        - type
        - name
        - email
        - phone
      additionalProperties: false
    UsdBeneficiaryIndividualHolder:
      type: object
      properties:
        type:
          type: string
          enum:
            - individual
        first_name:
          type: string
          minLength: 1
          example: Ana
        last_name:
          type: string
          minLength: 1
          example: Lopez
        email:
          type: string
          format: email
        phone:
          type: string
          description: E.164 with the leading `+`.
          example: '+17189042371'
        occupation_id:
          type: integer
          exclusiveMinimum: 0
          description: >-
            The occupation of the person: an `id` from `occupations` in `GET
            /v2/lists`.
          example: 504
      required:
        - type
        - first_name
        - last_name
        - email
        - phone
        - occupation_id
      additionalProperties: false
  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.