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

# Simulate a USD beneficiary outcome (sandbox only)

> Sandbox only. Make the check of a USD beneficiary give an outcome now, to test your handling of it. You get the same `beneficiary.*` webhook as for a real outcome. With no call, a `pending` beneficiary becomes `active` about 10 seconds after you register it. In any other environment this route answers `403 sandbox_only`.



## OpenAPI

````yaml /v2/openapi.json post /beneficiaries/{id}/simulate
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}/simulate:
    post:
      summary: Simulate a USD beneficiary outcome (sandbox only)
      description: >-
        Sandbox only. Make the check of a USD beneficiary give an outcome now,
        to test your handling of it. You get the same `beneficiary.*` webhook as
        for a real outcome. With no call, a `pending` beneficiary becomes
        `active` about 10 seconds after you register it. In any other
        environment this route answers `403 sandbox_only`.
      parameters:
        - schema:
            type: string
            description: The beneficiary id (UUID).
          required: true
          description: The beneficiary id (UUID).
          name: id
          in: path
        - $ref: '#/components/parameters/HermesOrg'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateBeneficiary'
      responses:
        '200':
          description: The USD beneficiary, with its new status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsdBeneficiary'
        '400':
          description: >-
            `validation_error`: the body is not `{outcome}` with a known
            outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            `sandbox_only` outside the sandbox. Also the access codes of every
            `/v2` route.
          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'
        '409':
          description: >-
            `conflict`: the beneficiary cannot get this outcome from its status.
            A `rejected` one never changes.
          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:
    SimulateBeneficiary:
      type: object
      properties:
        outcome:
          type: string
          enum:
            - active
            - inactive
            - rejected
          description: >-
            What the beneficiary becomes: `rejected` from `pending`, `inactive`
            from `active`, `active` from `pending` or `inactive`.
          example: rejected
      required:
        - outcome
    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.