Beneficiaries

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:

​

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

​

Endpoints

• Create a Beneficiary: POST /v1/beneficiaries
• Update a Beneficiary: PUT /v1/beneficiaries/{id}
• List Beneficiaries: 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: GET /v1/beneficiaries/{id}
• Export Beneficiaries: GET /v1/beneficiaries/export
• Archive a Beneficiary: DELETE /v1/beneficiaries/{id} (archiving is terminal and frees the email address; in-flight payouts are unaffected)
• Acknowledge compliance: POST /v1/beneficiaries/{id}/compliance-acknowledgment
• Enroll with the provider: POST /v1/beneficiaries/{id}/enroll

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

• Invite Beneficiaries to submit details: POST /v1/beneficiaries/collection-invites
• Bulk-invite from CSV rows: POST /v1/beneficiaries/bulk-invites
• Cancel a collection request: DELETE /v1/beneficiaries/{id}/collection-requests/{requestId}

Bank accounts, which payouts name explicitly via bank_account_id:

• List bank accounts: GET /v1/beneficiaries/{id}/bank-accounts (identifiers masked to last4)
• Register a bank account: POST /v1/beneficiaries/{id}/bank-accounts
• Update a bank account: 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.