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

# Get a USD beneficiary

> One USD beneficiary by id: poll it until `status` is `active`. USD beneficiaries are for USD payouts only. Every other asset pays an inline `destination`.



## OpenAPI

````yaml /v2/openapi.json get /beneficiaries/{id}
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/{id}:
    get:
      summary: Get a USD beneficiary
      description: >-
        One USD beneficiary by id: poll it until `status` is `active`. USD
        beneficiaries are for USD payouts only. Every other asset pays an inline
        `destination`.
      parameters:
        - schema:
            type: string
            description: The beneficiary id (UUID).
          required: true
          description: The beneficiary id (UUID).
          name: id
          in: path
        - $ref: '#/components/parameters/HermesOrg'
      responses:
        '200':
          description: The USD beneficiary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsdBeneficiary'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            Organization suspended, request IP not on the allowlist, or no
            multi-asset access yet (`onboarding_incomplete` /
            `access_suspended`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No USD beneficiary with this id in your organization.
          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:
    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
  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.