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

# List USD beneficiaries

> Every USD beneficiary of your organization, newest first. USD beneficiaries are for USD payouts only. Every other asset pays an inline `destination`.



## OpenAPI

````yaml /v2/openapi.json get /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:
    get:
      summary: List USD beneficiaries
      description: >-
        Every USD beneficiary of your organization, newest first. USD
        beneficiaries are for USD payouts only. Every other asset pays an inline
        `destination`.
      parameters:
        - $ref: '#/components/parameters/HermesOrg'
      responses:
        '200':
          description: Your USD beneficiaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsdBeneficiaryList'
        '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'
        '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:
    UsdBeneficiaryList:
      type: object
      properties:
        beneficiaries:
          type: array
          items:
            $ref: '#/components/schemas/UsdBeneficiary'
      required:
        - beneficiaries
    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
    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
  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.