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

# Get Beneficiary

> Retrieve a specific beneficiary and their account details

Retrieve detailed information about a specific beneficiary, including all their associated payment accounts.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000',
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer your_api_key',
      },
    },
  );

  const beneficiary = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000',
    headers={
      'Authorization': 'Bearer your_api_key'
    }
  )

  beneficiary = response.json()
  ```
</RequestExample>

## Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier for the beneficiary (UUID format)
</ParamField>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Beneficiary not found",
    "error": "Not Found",
    "statusCode": 404
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the beneficiary
</ResponseField>

<ResponseField name="type" type="string">
  Beneficiary type: `individual` or `business`
</ResponseField>

<ResponseField name="name" type="string">
  Full name of the beneficiary
</ResponseField>

<ResponseField name="middleName" type="string">
  Middle name of the beneficiary
</ResponseField>

<ResponseField name="email" type="string">
  Email address of the beneficiary (if provided)
</ResponseField>

<ResponseField name="country" type="string">
  Country code (ISO 3166-1 alpha-2)
</ResponseField>

<ResponseField name="address" type="string">
  Address line 1 of the beneficiary
</ResponseField>

<ResponseField name="addressLine2" type="string">
  Address line 2 of the beneficiary
</ResponseField>

<ResponseField name="city" type="string">
  City of the beneficiary
</ResponseField>

<ResponseField name="postcode" type="string">
  Postal code of the beneficiary
</ResponseField>

<ResponseField name="countrySubdivision" type="string">
  State or province code (e.g. "NY")
</ResponseField>

<ResponseField name="notes" type="string">
  Notes about the beneficiary
</ResponseField>

<ResponseField name="accounts" type="array">
  Array of all payment accounts associated with this beneficiary

  <Expandable title="Account Object">
    <ResponseField name="id" type="string">
      Unique identifier for the account
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of payment account - `iban`: European IBAN account - `bank_account`:
      US bank account - `wallet`: Cryptocurrency wallet - `card`: Card account
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code (EUR, USD, USDC, EURC)
    </ResponseField>

    <ResponseField name="data" type="object">
      Account-specific payment details

      <Expandable title="IBAN Account Data">
        <ResponseField name="iban" type="string">
          International Bank Account Number
        </ResponseField>

        <ResponseField name="bic" type="string">
          Bank Identifier Code
        </ResponseField>
      </Expandable>

      <Expandable title="US Bank Account Data">
        <ResponseField name="accountNumber" type="string">
          Bank account number
        </ResponseField>

        <ResponseField name="routingNumber" type="string">
          Bank routing number
        </ResponseField>

        <ResponseField name="bankName" type="string">
          Bank name
        </ResponseField>
      </Expandable>

      <Expandable title="Crypto Wallet Data">
        <ResponseField name="network" type="string">
          Cryptocurrency network
        </ResponseField>

        <ResponseField name="address" type="string">
          Wallet address
        </ResponseField>

        <ResponseField name="extra" type="object">
          Additional network-specific data
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Account status - `active`: Account is active and can receive payments -
      `suspended`: Account is temporarily suspended - `closed`: Account is
      permanently closed
    </ResponseField>

    <ResponseField name="resolutionStatus" type="string">
      Whether the account number has been verified against the bank. Applies to
      Nigerian (NGN) bank accounts; other account types are always
      `unresolved`. One of: `unresolved` (not yet verified), `resolved`
      (confirmed to exist at the bank), `invalid` (rejected by the bank).
    </ResponseField>

    <ResponseField name="resolvedAccountName" type="string">
      The account-holder name returned by the bank when the account number was
      resolved. Present only when `resolutionStatus` is `resolved`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the account was created
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the account was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string">
  Beneficiary status - `active`: Beneficiary is active and can receive payments

  * `inactive`: Beneficiary is inactive - `suspended`: Beneficiary is suspended
    and cannot receive payments
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the beneficiary was created
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when the beneficiary was last updated
</ResponseField>

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

## Related Endpoints

* [Update Beneficiary](/api-reference/payouts/update-beneficiary) - Modify beneficiary information
* [Create Payout](/api-reference/payouts/create-payouts) - Send payment to this beneficiary
* [List Payouts](/api-reference/payouts/list-payouts) - Filter payouts by beneficiary ID