Skip to main content
POST
/
v1
/
beneficiaries
curl -X POST "https://api.zuba.com/v1/beneficiaries" \
  -H "Authorization: Bearer zuba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "middleName": "Michael",
    "email": "john.doe@example.com",
    "country": "US",
    "countrySubdivision": "NY",
    "address": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "postcode": "10001",
    "accounts": [
      {
        "type": "bank_account",
        "currency": "USD",
        "data": {
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "accountHolderName": "John Doe",
          "bankName": "Chase Bank"
        }
      }
    ]
  }'

{
  "id": "ben_1234567890abcdef",
  "type": "individual",
  "name": "John Doe",
  "middleName": "Michael",
  "email": "john.doe@example.com",
  "country": "US",
  "countrySubdivision": "NY",
  "address": "123 Main St",
  "addressLine2": "Apt 4B",
  "city": "New York",
  "postcode": "10001",
  "status": "active",
  "accounts": [
    {
      "id": "acc_abcdef1234567890",
      "type": "bank_account",
      "currency": "USD",
      "status": "active",
      "resolutionStatus": "unresolved",
      "data": {
        "accountNumber": "****7890",
        "routingNumber": "021000021",
        "accountHolderName": "John Doe",
        "bankName": "Chase Bank"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

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 beneficiary to receive payouts. A beneficiary represents the recipient of payments and includes their personal information and associated payment accounts (bank accounts, crypto wallets, etc.).

​
Idempotency

This endpoint is idempotent on the submitted account identifier. If any account in the request matches an existing active beneficiary for your account, the existing beneficiary is returned unchanged and no duplicate row is created. Matching is performed on:
  • iban for iban accounts
  • crAccount + bankCode for bank_account accounts (Nigerian bank accounts)
This means repeating a POST /v1/beneficiaries call with the same account data will always return the same beneficiary id and is safe to retry. The same resolution applies when submitting inline beneficiary data via POST /v1/payouts.

​
Request

​
type
enum
default:"individual"
Beneficiary type. Defaults to individual if not provided.
​
name
string
required
Full name of the beneficiary (2-100 characters)
​
middleName
string
Middle name of the beneficiary (max 100 characters)
​
country
string
required
Country code (ISO 3166-1 alpha-2, e.g., “DE”, “GB”, “US”)
​
email
string
Email address of the beneficiary
​
address
string
Address line 1 of the beneficiary (max 200 characters)
​
addressLine2
string
Address line 2 of the beneficiary (max 200 characters)
​
city
string
required
City of the beneficiary (max 100 characters)
​
postcode
string
Postal code of the beneficiary (max 20 characters)
​
countrySubdivision
string
State or province code (e.g. “NY” for New York). Required for US beneficiaries.
​
notes
string
Optional notes about the beneficiary (max 500 characters)
​
accounts
array
required
Array of payment accounts for this beneficiary

​
Account Details by Type

​
IBAN Account (SEPA)

{
  "type": "iban",
  "currency": "EUR",
  "data": {
    "iban": "DE89370400440532013000",
    "accountHolderName": "John Doe",
    "bic": "DEUTDEFF"
  }
}

​
Bank Account (US ACH)

{
  "type": "bank_account",
  "currency": "USD",
  "data": {
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "accountHolderName": "John Doe",
    "bankName": "Chase Bank"
  }
}

​
Nigerian Bank Account

{
  "type": "bank_account",
  "currency": "NGN",
  "data": {
    "bankCode": "044",
    "crAccount": "1234567890"
  }
}

​
Card Account

{
  "type": "card",
  "currency": "EUR",
  "data": {
    "cardNumber": "4242424242424242",
    "accountHolderName": "John Doe"
  }
}

​
Response

​
id
string
Unique identifier for the beneficiary (UUID)
​
type
string
Beneficiary type: individual or business
​
name
string
Full name of the beneficiary
​
middleName
string
Middle name of the beneficiary
​
email
string
Email address of the beneficiary
​
country
string
Country code (ISO 3166-1 alpha-2)
​
address
string
Address line 1 of the beneficiary
​
addressLine2
string
Address line 2 of the beneficiary
​
city
string
City of the beneficiary
​
postcode
string
Postal code of the beneficiary
​
countrySubdivision
string
State or province code (e.g. “NY”)
​
notes
string
Notes about the beneficiary
​
status
string
Beneficiary status: active, pending, suspended
​
accounts
array
Array of associated payment accounts
​
createdAt
string
ISO timestamp when the beneficiary was created
​
updatedAt
string
ISO timestamp when the beneficiary was last updated

​
Examples

curl -X POST "https://api.zuba.com/v1/beneficiaries" \
  -H "Authorization: Bearer zuba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "middleName": "Michael",
    "email": "john.doe@example.com",
    "country": "US",
    "countrySubdivision": "NY",
    "address": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "postcode": "10001",
    "accounts": [
      {
        "type": "bank_account",
        "currency": "USD",
        "data": {
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "accountHolderName": "John Doe",
          "bankName": "Chase Bank"
        }
      }
    ]
  }'

{
  "id": "ben_1234567890abcdef",
  "type": "individual",
  "name": "John Doe",
  "middleName": "Michael",
  "email": "john.doe@example.com",
  "country": "US",
  "countrySubdivision": "NY",
  "address": "123 Main St",
  "addressLine2": "Apt 4B",
  "city": "New York",
  "postcode": "10001",
  "status": "active",
  "accounts": [
    {
      "id": "acc_abcdef1234567890",
      "type": "bank_account",
      "currency": "USD",
      "status": "active",
      "resolutionStatus": "unresolved",
      "data": {
        "accountNumber": "****7890",
        "routingNumber": "021000021",
        "accountHolderName": "John Doe",
        "bankName": "Chase Bank"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Multiple Account Types

You can add multiple accounts to a single beneficiary: 
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "country": "DE",
  "address": "Hauptstraße 123",
  "addressLine2": "Gebäude B",
  "city": "Berlin",
  "postcode": "10115",
  "accounts": [
    {
      "type": "iban",
      "currency": "EUR",
      "data": {
        "iban": "DE89370400440532013000",
        "accountHolderName": "Jane Smith",
        "bic": "DEUTDEFF"
      }
    },
    {
      "type": "wallet",
      "currency": "USDC",
      "data": {
        "address": "0x742d35Cc6634C0532925a3b8D33AA5e0000000000",
        "network": "ETHEREUM"
      }
    }
  ]
}

​
Error Responses

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "BAD_REQUEST",
  "timestamp": "2026-01-15T12:12:24.062Z",
  "path": "/v1/beneficiaries",
  "details": [
    {
      "field": "accounts.0.data",
      "message": "bankCode '123123333' is not a recognized Nigerian bank code",
      "value": {
        "crAccount": "1234567890",
        "bankCode": "123123333"
      }
    }
  ]
}

​
Next Steps

After creating a beneficiary:
  1. Send your first payout to the beneficiary
  2. Check SEPA reachability for EU bank accounts
  3. Set up webhooks to receive beneficiary status updates