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

> Two ways to onboard the people you pay, the compliance attestation that gates payouts, and what makes a bank account usable.

A **Beneficiary** is a person or business your Business pays. Before a payout
can name them, three things must be true: their identity is on file, their
compliance status is `compliant`, and they have a `payout_usable` bank
account. This page explains how each of those comes about, and the two
different paths that get you there.

## Two onboarding paths

**You enter the details.** If you already hold the beneficiary's identity and
bank details, [create them directly](/api-reference/beneficiaries-create) and
[register their bank account](/api-reference/beneficiaries-bank-accounts-create).
This is the path the [quickstart](/quickstart) walks.

**The beneficiary enters their own.** [Send a collection
invite](/api-reference/beneficiaries-collection-invites) and Cleff emails the
beneficiary a secure link to a Cleff-hosted form where they submit their own
profile and bank details. This keeps the most sensitive data (bank account
numbers, tax details) out of your systems entirely.

Both paths are batch-capable: collection invites accept 1..N beneficiaries in
one call, and [bulk invites](/api-reference/beneficiaries-bulk-invites) accept
up to 500 CSV-shaped rows, creating an identity stub per row and inviting each
one. The dashboard's invite buttons drive these same endpoints.

## How collection links behave

* Each link carries a **scope**, which is what the form may collect: a full
  onboarding, just new bank details, or tax documents. It authorizes only
  that submission; it is not a login and grants no standing access.
* Links **expire after 7 days**. Re-inviting issues a fresh link and
  invalidates the prior one; you can also
  [cancel a live request](/api-reference/beneficiaries-collection-requests-cancel)
  outright.
* Live links are visible as `pending_requests` on the beneficiary, and
  submission is observable via `collection_status` and
  `details_submitted_at`.
* Invite emails render in your Business's brand if you have configured one
  (dashboard **Settings → Company → Brand**), always with a "Powered by Cleff"
  attribution, and with a sandbox banner when sent from sandbox.

## The compliance attestation

Payout creation requires the beneficiary to be `compliant`. Compliance is
KYC for a `person` and KYB for a `business`, and in the current model it is
your Business that attests to it: passing `acknowledged: true` at creation, or
calling [acknowledge compliance](/api-reference/beneficiaries-acknowledge)
later, records that your Business has independently verified the
beneficiary's identity and moves them `pending → compliant`, stamping
`acknowledged_at`.

Editing a PII trigger field (legal name, date of birth, tax id, country)
after acknowledgment sets `reacknowledgment_required`; re-acknowledge to
clear it before the next payout. Cleff can also place a beneficiary in
`suspended`, which blocks payouts until the hold is lifted.

The schema is shaped so that provider-verified compliance can replace the
attestation model without breaking your integration.

## Bank accounts

Bank accounts are a sub-resource of the beneficiary, and payouts name one
explicitly; a beneficiary can hold several (different currencies, a
replacement after a failed payout). Three independent checks fold into the one
flag worth reading, `payout_usable`:

1. **Verified**: the account belongs to a compliance-acknowledged
   beneficiary. Registration against an already-`compliant` beneficiary
   verifies immediately.
2. **Validated**: the routing details pass Cleff's format checks (US ABA
   checksum, IBAN mod-97 for IBAN corridors).
3. **Not rail-rejected**: the payout rail has not refused the account. A
   rejection reason, when present, is surfaced as `rail_rejection_reason`.

Account identifiers are encrypted at rest and masked to `last4` in every
response; the full number is never serialized back. If a payout is refused
because of the destination account, the
[error catalogue](/errors#bank-accounts) names the exact check that failed and
the resolving action.