> For the complete documentation index, see [llms.txt](https://docs.aquanow.io/aquanow/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aquanow.io/aquanow/api-endpoints-or-v2.0/funding-api/address-book/manage-beneficiaries.md).

# Manage Beneficiaries

Add and reuse beneficiary profiles across your payout instructions

A beneficiary represents an individual or business created from a full set of KYC details. Once created, reference the returned `beneficiaryId` via `kycDetails.beneficiaryId` on Manage Crypto Addresses endpoints to attach payout instructions without re-submitting KYC.

{% hint style="info" %}
This endpoint requires **full** KYC details (it is the endpoint that creates the beneficiary). Unlike the address book endpoints, it does not accept a `beneficiaryId` reference.
{% endhint %}

#### Headers

All requests require the following headers.

| Name        | Type   | Required | Description                             |
| ----------- | ------ | -------- | --------------------------------------- |
| x-api-key   | String | Yes      | API Auth Key                            |
| x-signature | String | Yes      | Signature created using your API secret |
| x-nonce     | String | Yes      | Timestamp in millisecond                |

### Create Beneficiary

Create a new beneficiary from KYC details. Returns a `beneficiaryId` to reference later.

<mark style="color:blue;">`POST`</mark> `https://api.aquanow.io/users/v2/beneficiaries`

**Request Body**

| Name                                 | Type   | Required    | Description                                                                   |
| ------------------------------------ | ------ | ----------- | ----------------------------------------------------------------------------- |
| beneficiaryType                      | String | Yes         | "INDIVIDUAL" or "BUSINESS". Determines which KYC fields are required          |
| kycDetails                           | Object | Yes         | Full KYC details for the beneficiary (fields below depend on beneficiaryType) |
| kycDetails.firstName                 | String | Conditional | Individual only. Required for INDIVIDUAL                                      |
| kycDetails.lastName                  | String | Conditional | Individual only. Required for INDIVIDUAL                                      |
| kycDetails.dateOfBirth               | String | Conditional | Individual only, YYYY-MM-DD. Required for INDIVIDUAL                          |
| kycDetails.occupation                | String | Conditional | Individual only. Required for INDIVIDUAL                                      |
| kycDetails.companyLegalName          | String | Conditional | Business only. Required for BUSINESS                                          |
| kycDetails.industry                  | String | Conditional | Business only. Required for BUSINESS                                          |
| kycDetails.registrationNumber        | String | Conditional | Business only. Required for BUSINESS                                          |
| kycDetails.registrationNumberRegion  | String | Conditional | Business only. Required for BUSINESS                                          |
| kycDetails.registrationNumberCountry | String | Conditional | Business only. Required for BUSINESS                                          |
| kycDetails.telephone                 | String | Yes         | Required for both INDIVIDUAL and BUSINESS                                     |
| kycDetails.address                   | Object | Yes         | Beneficiary physical address (fields below)                                   |
| kycDetails.address.addressLine1      | String | Yes         | The primary street address line                                               |
| kycDetails.address.addressLine2      | String | No          | Street address line 2 (e.g., suite, unit)                                     |
| kycDetails.address.city              | String | Yes         | City, town, or village                                                        |
| kycDetails.address.region            | String | Yes         | State/province/region                                                         |
| kycDetails.address.postalCode        | String | No          | Postal code                                                                   |
| kycDetails.address.country           | String | Yes         | Two-letter ISO country code (e.g., "US")                                      |
| externalReferenceId                  | String | No          | Client-defined reference. Reused values return 409, making retries idempotent |

**Response**

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "beneficiaryId": "b1e7c3d2-9f4a-4c8b-a1d2-6e5f7a8b9c0d",
  "status": "PENDING_INSTRUCTIONS",
  "createdAt": "2026-01-21T10:30:00.000Z",
  "externalReferenceId": "client-ref-12345"
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  "message": "beneficiaryType is required and must be \"INDIVIDUAL\" or \"BUSINESS\""
}
```

Or (missing required KYC field):

```json
{
  "message": "firstName is required"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
  "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="404: Not found" %}

```json
{
  "message": "User entity not found"
}
```

{% endtab %}

{% tab title="409: Conflict" %}
When `externalReferenceId` matches an already-created beneficiary.

```json
{
  "message": "A beneficiary with this externalReferenceId already exists"
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```json
{
  "message": "Failed to create beneficiary"
}
```

{% endtab %}
{% endtabs %}

**Example Request - Individual**

```json
{
  "beneficiaryType": "INDIVIDUAL",
  "externalReferenceId": "client-ref-12345",
  "kycDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-14",
    "occupation": "Software Engineer",
    "telephone": "+1-202-555-0134",
    "address": {
      "addressLine1": "123 Main Street",
      "city": "New York",
      "region": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}
```

**Example Request - Business**

```json
{
  "beneficiaryType": "BUSINESS",
  "externalReferenceId": "client-ref-67890",
  "kycDetails": {
    "companyLegalName": "Acme Corporation Inc.",
    "industry": "Technology",
    "registrationNumber": "1234567",
    "registrationNumberRegion": "ON",
    "registrationNumberCountry": "CA",
    "telephone": "+1-416-555-0100",
    "address": {
      "addressLine1": "789 Corporate Boulevard",
      "city": "Toronto",
      "region": "ON",
      "postalCode": "M5H 2N2",
      "country": "CA"
    }
  }
}
```