Skip to main content
GET
/
v1
/
beneficiaries
/
{id}
curl -X GET "https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer your_api_key"

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "individual",
  "name": "John Doe",
  "middleName": "Michael",
  "email": "john.doe@example.com",
  "country": "DE",
  "address": "Hauptstraße 123",
  "addressLine2": "Gebäude B",
  "city": "Berlin",
  "postcode": "10115",
  "accounts": [
    {
      "id": "account-123e4567-e89b-12d3-a456-426614174000",
      "type": "iban",
      "currency": "EUR",
      "data": {
        "iban": "DE89370400440532013000",
        "bic": "DEUTDEFF"
      },
      "status": "active",
      "resolutionStatus": "unresolved",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "account-456e7890-e89b-12d3-a456-426614174001",
      "type": "bank_account",
      "currency": "NGN",
      "data": {
        "bankCode": "058",
        "crAccount": "0123456789"
      },
      "status": "active",
      "resolutionStatus": "resolved",
      "resolvedAccountName": "JANE DOE",
      "createdAt": "2024-01-16T14:20:00Z",
      "updatedAt": "2024-01-16T14:20:00Z"
    }
  ],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T14:20:00Z"
}
Retrieve detailed information about a specific beneficiary, including all their associated payment accounts. 
curl -X GET "https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer your_api_key"

​
Path Parameters

​
id
string
required
Unique identifier for the beneficiary (UUID format)
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "individual",
  "name": "John Doe",
  "middleName": "Michael",
  "email": "john.doe@example.com",
  "country": "DE",
  "address": "Hauptstraße 123",
  "addressLine2": "Gebäude B",
  "city": "Berlin",
  "postcode": "10115",
  "accounts": [
    {
      "id": "account-123e4567-e89b-12d3-a456-426614174000",
      "type": "iban",
      "currency": "EUR",
      "data": {
        "iban": "DE89370400440532013000",
        "bic": "DEUTDEFF"
      },
      "status": "active",
      "resolutionStatus": "unresolved",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "account-456e7890-e89b-12d3-a456-426614174001",
      "type": "bank_account",
      "currency": "NGN",
      "data": {
        "bankCode": "058",
        "crAccount": "0123456789"
      },
      "status": "active",
      "resolutionStatus": "resolved",
      "resolvedAccountName": "JANE DOE",
      "createdAt": "2024-01-16T14:20:00Z",
      "updatedAt": "2024-01-16T14:20:00Z"
    }
  ],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T14:20:00Z"
}

​
Response Fields

​
id
string
Unique identifier for the beneficiary
​
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 (if provided)
​
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
​
accounts
array
Array of all payment accounts associated with this beneficiary
​
status
string
Beneficiary status - active: Beneficiary is active and can receive payments
  • inactive: Beneficiary is inactive - suspended: Beneficiary is suspended and cannot receive payments
​
createdAt
string
ISO 8601 timestamp when the beneficiary was created
​
updatedAt
string
ISO 8601 timestamp when the beneficiary was last updated

​
Use Cases

This endpoint is useful for:
  • Verification: Confirming beneficiary details before creating payouts
  • Account Management: Viewing all payment accounts for a beneficiary
  • Status Checking: Verifying if a beneficiary is active and can receive payments
  • Audit Trail: Retrieving creation and update timestamps