> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zuba.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new beneficiary

> Create a new beneficiary with their account details for payouts. Idempotent: if any submitted account (IBAN or NGN crAccount+bankCode) matches an existing active beneficiary for this client, the existing beneficiary is returned unchanged instead of creating a duplicate.



## OpenAPI

````yaml /openapi.json post /v1/beneficiaries
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Comprehensive payment platform API supporting fiat and crypto payments,
    currency conversion, and compliance management
  title: Zuba Payment Platform API
  version: '1.0'
servers: []
security: []
tags:
  - description: Manage M2M API keys and credentials
    name: API Keys
  - description: Internal ledger accounts and transactions
    name: Ledger
  - description: Handle incoming payments and deposits
    name: Pay-ins
  - description: Manage payouts, beneficiaries, and SEPA transfers
    name: Payouts
  - description: Manage outbound webhook endpoints and deliveries
    name: Webhooks
paths:
  /v1/beneficiaries:
    post:
      tags:
        - Payouts
      summary: Create a new beneficiary
      description: >-
        Create a new beneficiary with their account details for payouts.
        Idempotent: if any submitted account (IBAN or NGN crAccount+bankCode)
        matches an existing active beneficiary for this client, the existing
        beneficiary is returned unchanged instead of creating a duplicate.
      operationId: PayoutController_createBeneficiary
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBeneficiaryDto'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryDto'
          description: Beneficiary created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
          description: Validation failed - invalid beneficiary data
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
        - bearer: []
components:
  schemas:
    CreateBeneficiaryDto:
      properties:
        accounts:
          description: Array of payment accounts for this beneficiary
          example:
            - currency: EUR
              data:
                accountHolderName: John Doe
                bic: DEUTDEFF
                iban: DE89370400440532013000
              type: iban
          items:
            $ref: '#/components/schemas/CreateAccountDto'
          type: array
        address:
          description: Address line 1 of the beneficiary (max 200 characters)
          example: Hauptstraße 123
          maxLength: 200
          type: string
        addressLine2:
          description: Address line 2 of the beneficiary (max 200 characters)
          example: Apt 4B, 3rd Floor
          maxLength: 200
          type: string
        city:
          description: >-
            City of the beneficiary. May be required depending on corridor — use
            GET /v1/payouts/requirements to check.
          example: Berlin
          maxLength: 100
          type: string
        country:
          description: Country code (ISO 3166-1 alpha-2, e.g., "DE", "GB", "US")
          example: DE
          maxLength: 2
          minLength: 2
          type: string
        countrySubdivision:
          description: Country subdivision code (e.g., US state code "NY", "CA")
          example: NY
          maxLength: 50
          type: string
        dateOfBirth:
          description: >-
            Date of birth in YYYY-MM-DD format (individual beneficiaries only).
            Required for individual crypto counterparties when the Sumsub Travel
            Rule gate is enabled.
          example: '1985-05-20'
          type: string
        email:
          description: Email address of the beneficiary
          example: john.doe@example.com
          format: email
          type: string
        id:
          description: >-
            UUID of an existing beneficiary. If provided, other fields are
            ignored and the existing beneficiary is referenced.
          example: cc82fa1d-fc7a-478c-a734-d3bce40464e7
          format: uuid
          type: string
        middleName:
          description: Middle name of the beneficiary (max 100 characters)
          example: James
          maxLength: 100
          type: string
        name:
          description: Full name of the beneficiary (2-100 characters)
          example: John Doe
          maxLength: 100
          minLength: 2
          type: string
        notes:
          description: Optional notes about the beneficiary (max 500 characters)
          example: Regular client, prefers SEPA Instant
          maxLength: 500
          type: string
        postcode:
          description: Postal code of the beneficiary
          example: '10115'
          maxLength: 20
          type: string
        type:
          default: individual
          description: Beneficiary type. Defaults to "individual" if not provided.
          enum:
            - individual
            - business
          example: individual
          type: string
      required:
        - name
        - country
        - accounts
      type: object
    BeneficiaryDto:
      properties:
        accounts:
          description: Array of associated payment accounts
          items:
            $ref: '#/components/schemas/AccountDto'
          type: array
        address:
          description: Address line 1 of the beneficiary
          example: Hauptstraße 123
          type: string
        addressLine2:
          description: Address line 2 of the beneficiary
          example: Apt 4B, 3rd Floor
          type: string
        city:
          description: City of the beneficiary
          example: Berlin
          type: string
        country:
          description: Country code (ISO 3166-1 alpha-2)
          example: DE
          type: string
        countrySubdivision:
          description: Country subdivision code (e.g., US state code "NY", "CA")
          example: NY
          type: string
        createdAt:
          description: ISO timestamp when the beneficiary was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        dateOfBirth:
          description: Date of birth in YYYY-MM-DD format (individual beneficiaries only).
          example: '1985-05-20'
          type: string
        email:
          description: Email address of the beneficiary
          example: john.doe@example.com
          type: string
        id:
          description: Unique identifier for the beneficiary
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
        middleName:
          description: Middle name of the beneficiary
          example: James
          type: string
        name:
          description: Full name of the beneficiary
          example: John Doe
          type: string
        notes:
          description: Notes about the beneficiary
          example: Regular client, prefers SEPA Instant
          type: string
        postcode:
          description: Postal code of the beneficiary
          example: '10115'
          type: string
        status:
          description: Beneficiary status
          enum:
            - active
            - inactive
            - suspended
          example: active
          type: string
        type:
          description: Beneficiary type
          enum:
            - individual
            - business
          example: individual
          type: string
        updatedAt:
          description: ISO timestamp when the beneficiary was last updated
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - name
        - type
        - country
        - accounts
        - status
        - createdAt
        - updatedAt
      type: object
    ValidationErrorResponseDto:
      properties:
        details:
          description: Array of detailed validation errors
          example:
            - field: accounts.0.data.crAccount
              message: crAccount must be exactly 10 digits for Nigerian accounts
              value: '12345678901'
          items:
            $ref: '#/components/schemas/ValidationErrorDetailDto'
          type: array
        error:
          description: Error type identifier
          example: BAD_REQUEST
          type: string
        message:
          description: Error summary message
          example: Validation failed
          type: string
        path:
          description: Request path that generated the error
          example: /v1/beneficiaries
          type: string
        statusCode:
          description: HTTP status code
          example: 400
          type: number
        timestamp:
          description: ISO timestamp when the error occurred
          example: '2024-01-15T10:30:00.000Z'
          type: string
      required:
        - statusCode
        - message
        - error
        - timestamp
        - path
        - details
      type: object
    CreateAccountDto:
      properties:
        currency:
          description: >-
            Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP,
            USDC, EURC, NGN. Contact your account manager to enable additional
            currencies.
          enum:
            - EUR
            - USD
            - GBP
            - USDC
            - USDT
            - EURC
            - NGN
            - XOF
            - XAF
            - GHS
          example: EUR
          type: string
        data:
          additionalProperties: true
          description: Account data specific to the account type
          example:
            bic: DEUTDEFF
            iban: DE89370400440532013000
          type: object
        type:
          description: Type of payment account
          enum:
            - iban
            - card
            - bank_account
            - wallet
            - swift
            - mobile
          example: iban
          type: string
      required:
        - type
        - currency
        - data
      type: object
    AccountDto:
      properties:
        createdAt:
          description: Creation timestamp
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        currency:
          description: >-
            Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP,
            USDC, EURC, NGN. Contact your account manager to enable additional
            currencies.
          enum:
            - EUR
            - USD
            - GBP
            - USDC
            - USDT
            - EURC
            - NGN
            - XOF
            - XAF
            - GHS
          example: EUR
          type: string
        data:
          additionalProperties: true
          description: Account data specific to the account type
          example:
            bic: DEUTDEFF
            iban: DE89370400440532013000
          type: object
        id:
          description: Unique identifier for the account
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
        resolutionStatus:
          description: >-
            Resolution status of the account number against the bank (NGN bank
            accounts only).
          enum:
            - unresolved
            - resolved
            - invalid
          example: resolved
          type: string
        resolvedAccountName:
          description: >-
            Account-holder name returned by the bank when the account was
            resolved, if available.
          example: JANE DOE
          type: string
        status:
          description: Status of the account
          enum:
            - active
            - suspended
            - closed
          example: active
          type: string
        type:
          description: Type of payment account
          enum:
            - iban
            - card
            - bank_account
            - wallet
            - swift
            - mobile
          example: iban
          type: string
        updatedAt:
          description: Last update timestamp
          example: '2024-01-15T10:35:00Z'
          format: date-time
          type: string
      required:
        - id
        - type
        - currency
        - data
        - status
        - createdAt
        - updatedAt
      type: object
    ValidationErrorDetailDto:
      properties:
        code:
          description: >-
            Stable machine-readable code for client-side branching. Present on
            provider structural-validation failures (e.g.
            MISSING_BENEFICIARY_NAME, INVALID_IBAN, BENEFICIARY_INCOMPLETE);
            absent on generic DTO validation errors.
          example: MISSING_BENEFICIARY_NAME
          type: string
        field:
          description: The field path that failed validation
          example: accounts.0.data.crAccount
          type: string
        message:
          description: Human-readable error message describing the validation failure
          example: crAccount must be exactly 10 digits for Nigerian accounts
          type: string
        value:
          description: The invalid value that was provided (may be omitted for security)
          example: '12345678901'
          type: object
      required:
        - field
        - message
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: Enter Auth0 JWT token
      scheme: bearer
      type: http

````