> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiaries

> Register and retrieve the payees who receive payouts from your Business.

A **Beneficiary** is a payee of your Business: a person or a business that
receives payouts. Every Beneficiary
has an explicit `compliance_status` that gates payout creation. The compliance process is
**KYC** for a `person` Beneficiary and **KYB** for a `business` (derived from
`beneficiary_type`); the status values are shared:

| Status      | Meaning                                                     |
| ----------- | ----------------------------------------------------------- |
| `pending`   | Registered but not yet compliance-cleared. Payouts blocked. |
| `compliant` | Compliance cleared (KYC/KYB). Payouts permitted.            |
| `suspended` | Compliance hold. Payouts blocked.                           |

## Compliance acknowledgment (MVP)

Cleff runs a **Business-acknowledgment** compliance model: by submitting `acknowledged: true`
on registration, your Business attests that it has independently verified the Beneficiary's
identity (KYC for a person, KYB for a business). The Beneficiary transitions to `compliant`
immediately and `acknowledged_at` is recorded. Omit the flag (or pass `false`) to leave the
Beneficiary in `pending`.

When provider-verified compliance ships (Routefusion), the same provider interface will
flip to webhook-driven activation. The schema is already in place to keep that change
non-breaking for your integration.

## Bank details

`bank_details` is a corridor-flexible payload modeled after Routefusion / Lightspark Grid
/ Mercury / Deel. Required fields work for any corridor; identifier fields are
corridor-specific.

| Field                 | Required | Notes                                        |
| --------------------- | -------- | -------------------------------------------- |
| `account_holder_name` | yes      | Legal name on the bank account               |
| `country`             | yes      | ISO 3166-1 alpha-2 of the **bank's** country |
| `currency`            | yes      | ISO 4217                                     |
| `account_number`      | one of   | Domestic account number (US/JP/etc.)         |
| `iban`                | one of   | Required for European corridors              |
| `routing_code`        | optional | US ABA, UK sort code, BR branch code, etc.   |
| `swift_bic`           | optional | Required for cross-border SWIFT routing      |
| `bank_name`           | optional |                                              |

At least one of `iban` or `account_number` must be present; otherwise the request fails
with `error.code = "validation_failed"` and `details[].code = "missing_account_identifier"`.

<Note>
  Validation in MVP is intentionally permissive. Per-corridor format checks (IBAN checksum, ABA
  structure, etc.) will tighten when the live Routefusion disbursement integration ships.
</Note>

## Endpoints

* [Create a Beneficiary](/api-reference/beneficiaries-create): `POST /v1/beneficiaries`
* [Update a Beneficiary](/api-reference/beneficiaries-update): `PUT /v1/beneficiaries/{id}`
* [List Beneficiaries](/api-reference/beneficiaries-list): `GET /v1/beneficiaries`
  (cursor-paginated; `limit` defaults to 25, max 100; pass the previous response's
  `next_cursor` as the `cursor` query param to page forward)
* [Retrieve a Beneficiary](/api-reference/beneficiaries-get): `GET /v1/beneficiaries/{id}`
* [Export Beneficiaries](/api-reference/beneficiaries-export): `GET /v1/beneficiaries/export`
* [Archive a Beneficiary](/api-reference/beneficiaries-archive): `DELETE /v1/beneficiaries/{id}`
  (archiving is terminal and frees the email address; in-flight payouts are unaffected)
* [Acknowledge compliance](/api-reference/beneficiaries-acknowledge): `POST /v1/beneficiaries/{id}/compliance-acknowledgment`
* [Enroll with the provider](/api-reference/beneficiaries-enroll): `POST /v1/beneficiaries/{id}/enroll`

Collection invites, the flow where the Beneficiary submits their own details
through a Cleff-hosted form (see
[Beneficiaries & compliance](/concepts/beneficiaries)):

* [Invite Beneficiaries to submit details](/api-reference/beneficiaries-collection-invites): `POST /v1/beneficiaries/collection-invites`
* [Bulk-invite from CSV rows](/api-reference/beneficiaries-bulk-invites): `POST /v1/beneficiaries/bulk-invites`
* [Cancel a collection request](/api-reference/beneficiaries-collection-requests-cancel): `DELETE /v1/beneficiaries/{id}/collection-requests/{requestId}`

Bank accounts, which payouts name explicitly via `bank_account_id`:

* [List bank accounts](/api-reference/beneficiaries-bank-accounts-list): `GET /v1/beneficiaries/{id}/bank-accounts` (identifiers masked to `last4`)
* [Register a bank account](/api-reference/beneficiaries-bank-accounts-create): `POST /v1/beneficiaries/{id}/bank-accounts`
* [Update a bank account](/api-reference/beneficiaries-bank-accounts-update): `PUT /v1/beneficiaries/{id}/bank-accounts/{accountId}`

## Tenant scoping

Beneficiaries are scoped to the Business and environment of the API key used to access
them: a sandbox key cannot read or modify a production Beneficiary, and a key issued to
one Business cannot access another Business's Beneficiaries. Cross-tenant fetches
return `404`.