# Recipients

### Create individual recipient

<mark style="color:$success;">`POST`</mark> : `/api/v1/recipients/individual`

Create an individual recipient with identity verification. A custodial Solana wallet is auto-generated.

**Required scopes:** `recipients:write` or `all`

**Headers**

| Header            | Value                     |
| ----------------- | ------------------------- |
| `x-api-key`       | Your secret key           |
| `Content-Type`    | `application/json`        |
| `Idempotency-Key` | Unique request identifier |

**Request body**

| Parameter         | Type   | Required | Description                                                |
| ----------------- | ------ | -------- | ---------------------------------------------------------- |
| `clientReference` | string | Optional | Your unique reference for this recipient (max 128 chars)   |
| `firstName`       | string | Required | Recipient's first name                                     |
| `lastName`        | string | Required | Recipient's last name                                      |
| `email`           | string | Required | Valid email address                                        |
| `phoneNumber`     | string | Required | E.164 format (e.g. `+2348012345678`)                       |
| `dateOfBirth`     | string | Required | `YYYY-MM-DD` format                                        |
| `country`         | string | Required | ISO 3166-1 alpha-2 code (e.g. `NG`, `KE`)                  |
| `idType`          | string | Required | `NIN`, `BVN`, `DRIVERS_LICENSE`, `VOTER_ID`, or `PASSPORT` |
| `idNumber`        | string | Required | Identity document number                                   |
| `address`         | object | Required | See address object below                                   |
| `bankAccount`     | object | Optional | For off-ramp payouts. See bank account object below        |

**Address object**

| Field        | Type   | Required | Description             |
| ------------ | ------ | -------- | ----------------------- |
| `street`     | string | Required | Street address          |
| `city`       | string | Required | City                    |
| `state`      | string | Required | State or province       |
| `postalCode` | string | Optional | Postal code             |
| `country`    | string | Required | ISO 3166-1 alpha-2 code |

**Bank account object**

| Field           | Type   | Required | Description                              |
| --------------- | ------ | -------- | ---------------------------------------- |
| `accountNumber` | string | Required | Bank account number                      |
| `bankName`      | string | Required | Bank name (e.g. GTBank)                  |
| `bankCode`      | string | Optional | Local bank code (e.g. `058` for Nigeria) |
| `currency`      | string | Required | ISO 4217 code (e.g. `NGN`, `KES`)        |
| `country`       | string | Required | ISO 3166-1 alpha-2 code                  |

CURL REQUEST:

```bash
curl -X POST https://zynta-lastmile-api.up.railway.app/api/v1/recipients/individual \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-001" \
  -d '{
    "firstName": "Chinedu",
    "lastName": "Okafor",
    "email": "chinedu.okafor@example.com",
    "phoneNumber": "+2348012345678",
    "dateOfBirth": "1990-05-15",
    "country": "NG",
    "idType": "NIN",
    "idNumber": "12345678901",
    "address": {
      "street": "15 Admiralty Way",
      "city": "Lagos",
      "state": "Lagos",
      "postalCode": "100001",
      "country": "NG"
    },
    "bankAccount": {
      "accountNumber": "0123456789",
      "bankName": "GTBank",
      "bankCode": "058",
      "currency": "NGN",
      "country": "NG"
    }
  }'
```

JAVASCRIPT EXAMPLE:

```javascript
const response = await fetch(
  'https://zynta-lastmile-api.up.railway.app/api/v1/recipients/individual',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'sk_test_...',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'onboard-001'
    },
    body: JSON.stringify({
      firstName: 'Chinedu',
      lastName: 'Okafor',
      email: 'chinedu.okafor@example.com',
      phoneNumber: '+2348012345678',
      dateOfBirth: '1990-05-15',
      country: 'NG',
      idType: 'NIN',
      idNumber: '12345678901',
      address: {
        street: '15 Admiralty Way',
        city: 'Lagos',
        state: 'Lagos',
        postalCode: '100001',
        country: 'NG'
      },
      bankAccount: {
        accountNumber: '0123456789',
        bankName: 'GTBank',
        bankCode: '058',
        currency: 'NGN',
        country: 'NG'
      }
    })
  }
);
const recipient = await response.json();
```

**Response `201 Created`**

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Chinedu",
  "lastName": "Okafor",
  "email": "chinedu.okafor@example.com",
  "country": "NG",
  "kycStatus": "PENDING",
  "walletAddress": "GqN8vW7Qxz4F9kP2mR5tY8uI3oP6aS9dF1gH4jK7lM0n",
  "createdAt": "2026-03-24T12:00:00Z"
}
```

***

### Create business recipient

<mark style="color:$success;">`POST`</mark> :  `/api/v1/recipients/business`

Create a business recipient with business verification. Requires at least one director.

**Required scopes:** `recipients:write` or `all`

**Request body**

| Parameter            | Type   | Required    | Description                                                                                                       |
| -------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `clientReference`    | string | Optional    | Your unique reference                                                                                             |
| `businessName`       | string | Required    | Legal business name                                                                                               |
| `registrationNumber` | string | Required    | Business registration number (e.g. `RC1234567`)                                                                   |
| `businessType`       | string | Conditional | `LIMITED_LIABILITY`, `SOLE_PROPRIETORSHIP`, `PARTNERSHIP`, or `NON_PROFIT`. **Required for Nigerian businesses.** |
| `email`              | string | Required    | Business email address                                                                                            |
| `phoneNumber`        | string | Required    | E.164 format                                                                                                      |
| `country`            | string | Required    | ISO 3166-1 alpha-2 code                                                                                           |
| `address`            | object | Required    | Same structure as individual address                                                                              |
| `directors`          | array  | Required    | Array of director objects (min 1). Each: `firstName`, `lastName`, `idType` (optional), `idNumber` (optional)      |
| `bankAccount`        | object | Optional    | Same structure as individual bank account                                                                         |

{% hint style="warning" %}
Nigerian businesses must include `businessType`. Omitting it returns a validation error.&#x20;
{% endhint %}

***

### Get recipient

<mark style="color:blue;">`GET`</mark>  : `/api/v1/recipients/{id}`

Retrieve a recipient by UUID. Returns full details including KYC status and wallet address.

**Required scopes:** `recipients:read` or `all`

### List recipients

<mark style="color:blue;">`GET`</mark>  :  `/api/v1/recipients`

Returns a paginated list of recipients for your partner account.

**Required scopes:** `recipients:read` or `all`

***

### Update individual recipient <a href="#update-individual-recipient" id="update-individual-recipient"></a>

<mark style="color:$warning;">`PATCH`</mark> : `/api/v1/recipients/{id}/individual`\
\
Update individual recipient information to resolve KYC rejections. Only include the fields that need correction.

{% hint style="info" %}
All fields are optional, send only what needs to change
{% endhint %}

| Parameter     | Type   | Description             |
| ------------- | ------ | ----------------------- |
| `firstName`   | string | Corrected first name    |
| `lastName`    | string | Corrected last name     |
| `dateOfBirth` | string | Corrected date of birth |
| `idType`      | string | Different ID type       |
| `idNumber`    | string | Corrected ID number     |
| `address`     | object | Updated address         |
| `bankAccount` | object | Updated bank details    |

***

### Update business recipient <a href="#update-business-recipient" id="update-business-recipient"></a>

<mark style="color:orange;">`PATCH`</mark> : `/api/v1/recipients/{id}/business`\
\
Update business recipient information to resolve verification rejections. Same partial-update pattern, only include changed fields.

***

### KYC statuses <a href="#kyc-statuses" id="kyc-statuses"></a>

| Status        | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `PENDING`     | Recipient created, verification not yet started                        |
| `IN_PROGRESS` | Verification is being processed                                        |
| `APPROVED`    | KYC approved — recipient can be used for transfers                     |
| `REJECTED`    | Verification failed — use the PATCH endpoint to remediate and resubmit |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zynta.com/api-reference/recipients.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.