# Cleff API

- [Welcome to Cleff](https://docs.usecleff.com/introduction.md): Payout orchestration for businesses that pay at volume.
- [Quickstart: send your first payout](https://docs.usecleff.com/quickstart.md): From signup to a disbursed sandbox payout. No review, no real money, about ten minutes.
- [Using the dashboard](https://docs.usecleff.com/dashboard.md): Everything an operations team runs from app.usecleff.com. No code required.
- [Go live](https://docs.usecleff.com/go-live.md): The path from sandbox to production: verification, pricing, and the production credential swap.
- [Environments](https://docs.usecleff.com/concepts/environments.md): Sandbox and production run in parallel, fully isolated, selected by the credential. Never by a parameter.
- [How money moves](https://docs.usecleff.com/concepts/how-money-moves.md): The funding account, the headroom check, the approval gate, and the life of a payout from creation to settlement.
- [Beneficiaries & compliance](https://docs.usecleff.com/concepts/beneficiaries.md): Two ways to onboard the people you pay, the compliance attestation that gates payouts, and what makes a bank account usable.
- [Authentication](https://docs.usecleff.com/authentication.md): API keys: shape, environment scoping, and rotation.
- [Errors](https://docs.usecleff.com/errors.md): The error envelope and every error code the Cleff API can return to an integration
- [Registration](https://docs.usecleff.com/api-reference/registration.md): Self-serve entry point: create your Business and its first owner.
- [Beneficiaries](https://docs.usecleff.com/api-reference/beneficiaries.md): Register and retrieve the payees who receive payouts from your Business.
- [Create a Beneficiary](https://docs.usecleff.com/api-reference/beneficiaries-create.md): Creates a Beneficiary scoped to the caller’s Business and environment. Submitting acknowledged=true transitions to compliant immediately.
- [Update a Beneficiary](https://docs.usecleff.com/api-reference/beneficiaries-update.md): Replaces the editable profile fields (name, alias, email, identity fields). Changing a PII trigger field (legal name, date of birth, country, tax id) on a compliant Beneficiary auto-raises reacknowledgment_required, blocking new Payouts until re-acknowledged. Identity-shape violations are rejected (…
- [List Beneficiaries](https://docs.usecleff.com/api-reference/beneficiaries-list.md)
- [Retrieve a Beneficiary](https://docs.usecleff.com/api-reference/beneficiaries-get.md)
- [Export Beneficiaries](https://docs.usecleff.com/api-reference/beneficiaries-export.md): The whole address book as an RFC-4180 CSV download: Beneficiary ID, name, type, and compliance status — the IDs a Business needs to seed a Bulk Payout CSV, and no further PII. Results are scoped to the caller's Business and environment.
- [Archive a Beneficiary](https://docs.usecleff.com/api-reference/beneficiaries-archive.md): Removes a Beneficiary from the address book: it stops appearing in `GET /v1/beneficiaries` and the CSV export, new Payouts to it are refused with BENEFICIARY_ARCHIVED, and every live collection link is cancelled. Nothing is deleted — `GET /v1/beneficiaries/{id}` still resolves it with `archived_at`…
- [Acknowledge compliance](https://docs.usecleff.com/api-reference/beneficiaries-acknowledge.md): Idempotent. Promotes pending → compliant on first attestation and clears the reacknowledgment_required soft flag on subsequent ones. Returns the updated Beneficiary.
- [Enroll a Beneficiary with the provider](https://docs.usecleff.com/api-reference/beneficiaries-enroll.md): Registers the Beneficiary as a Checkbook marketplace sub-user (create → KYC → verify → register default bank) so payouts reach them with zero rail-originated emails. The default bank is decrypted and registered at enrollment time. Idempotent per (beneficiary, environment, provider) — re-enrolling re…
- [Invite Beneficiaries to submit details](https://docs.usecleff.com/api-reference/beneficiaries-collection-invites.md): Batch-capable (1..N). Mints a scoped collection token per Beneficiary, advances each to `invited`, and enqueues a tokenized email to a Cleff-hosted form on the collect surface. A resend invalidates the prior link. The dashboard single-invite action is N=1 through this endpoint.
- [Bulk-invite Beneficiaries](https://docs.usecleff.com/api-reference/beneficiaries-bulk-invites.md): The invite-first flow, pluralized (1..500 rows): each row becomes an identity-only stub (identity_pending) and every persisted stub receives a full_onboarding collection link. Row failures (duplicate email, wrong-type identity field) are reported per row in `failed` and never abort the rest of the f…
- [Cancel a collection request](https://docs.usecleff.com/api-reference/beneficiaries-collection-requests-cancel.md): Invalidates a single live collection link (the token id surfaced in `pending_requests`) so it can no longer authorize a collect submit. Idempotent: re-cancelling an already-gone request (consumed, cancelled, or expired) is a success no-op. A request id not belonging to the named Beneficiary in the c…
- [List bank accounts](https://docs.usecleff.com/api-reference/beneficiaries-bank-accounts-list.md): Returns all statuses; identifiers are masked to last4. The full IBAN/account number is never serialized.
- [Register a bank account](https://docs.usecleff.com/api-reference/beneficiaries-bank-accounts-create.md): Registers a destination on behalf of the Beneficiary. The identifier is encrypted at rest; the response is the masked projection (last4 only). When the owning Beneficiary is compliant, the account is verified immediately.
- [Update a bank account](https://docs.usecleff.com/api-reference/beneficiaries-bank-accounts-update.md): Replaces the account’s editable details (holder name, corridor, routing) and re-runs Cleff-side validation, resetting validation_status. Malformed details are rejected (422) and the row is left unchanged. The identifier is re-encrypted at rest; the response is the masked projection.
- [Overview](https://docs.usecleff.com/api-reference/funding.md): The Cleff Account payouts draw from, and its sandbox top-up.
- [Get Cleff Account](https://docs.usecleff.com/api-reference/funding-account-get.md): Returns the Business's provisioned Cleff Account as a provider-neutral DTO — currency, balance, derived status, and the deposit instructions it funds the account with. Scoped to the caller's Business and environment.
- [Top up sandbox balance](https://docs.usecleff.com/api-reference/funding-sandbox-balance.md): Sets the available + total balance on the Business's sandbox Cleff Account so it can exercise payouts, without the dev CLI. Sandbox only: refused with SANDBOX_ONLY (409) on a production session, which can never touch a real wallet. The account must already be provisioned.
- [Overview](https://docs.usecleff.com/api-reference/payouts.md): The unit of money movement in Cleff. A Payout is created in pending_approval, validated by a Decision, and disbursed once approved.
- [Create a Payout](https://docs.usecleff.com/api-reference/payouts-create.md): Creates a Payout in pending_approval. Idempotent on (Business, environment, idempotency_key) within 24h — a duplicate within the window returns the original Payout with HTTP 200. In sandbox the Business must have a funded sandbox wallet: an empty (or unprovisioned) one is refused with SANDBOX_WALLET…
- [Bulk-create Payouts](https://docs.usecleff.com/api-reference/payouts-bulk-create.md): Creates one Payout per row through the single-payout write-path, tagged via { channel: 'csv', uploadId }. Row failures (bad shape, gate rejections) are reported per row and never abort the file. Idempotent by construction: each row's key derives from `${uploadId}:${index}`, so a byte-identical re-up…
- [List Payouts](https://docs.usecleff.com/api-reference/payouts-list.md)
- [Retrieve a Payout](https://docs.usecleff.com/api-reference/payouts-get.md): Returns the Payout with its current state. The response surfaces the latest disbursement attempt as a convenience triple — never the full attempts list, count, or prior attempt IDs.
- [Approve a Payout](https://docs.usecleff.com/api-reference/payouts-approve.md)
- [Reject a Payout](https://docs.usecleff.com/api-reference/payouts-reject.md)
- [Submit a Decision](https://docs.usecleff.com/api-reference/payouts-decisions-create.md): Canonical decision-submission endpoint per CONTEXT.md. Idempotent on decision_id within the Payout.
- [List Decisions](https://docs.usecleff.com/api-reference/payouts-decisions-list.md): Returns the approval decisions recorded against the Payout, newest-first.
- [Treasury](https://docs.usecleff.com/api-reference/treasury.md): The balance partitioned: fee earmark, working balance, committed outflow, and payout headroom.
- [Overview](https://docs.usecleff.com/api-reference/reporting.md): The Transactions ledger plus the payout, KPI, and beneficiary analytics behind the dashboard.
- [List Transactions](https://docs.usecleff.com/api-reference/reporting-transactions-list.md): A filtered read-model over Payout, projected to date / to-from / amount / account / derived-method / status, newest-first and paged by cursor. Narrow with any of beneficiary_id, status, and from/to date bounds (they compose); results are scoped to the caller's Business and environment, so a foreign…
- [Export Transactions](https://docs.usecleff.com/api-reference/reporting-transactions-export.md): The whole filtered ledger (not just one page) as an RFC-4180 CSV download, respecting the same beneficiary_id filter as the list endpoint. Results are scoped to the caller's Business and environment.
- [Payout volume](https://docs.usecleff.com/api-reference/reporting-payout-volume.md): The 'Payouts last 30 days' card payload: disbursed + settled Payout volume bucketed by created_at UTC day across the requested window (zero-filled, ascending), plus the % change vs the equal-length prior window. A pure read-model over Payout — nothing is stored. Results are scoped to the caller's Bu…
- [Hero KPIs](https://docs.usecleff.com/api-reference/reporting-hero-kpis.md): The dashboard hero strip payload: beneficiary retention %, Money-Out payout count, and average payout size per currency across the requested window, each with the % change vs the equal-length prior window. A pure read-model over Payout — nothing is stored. Results are scoped to the caller's Business…
- [Beneficiary analytics](https://docs.usecleff.com/api-reference/reporting-beneficiaries.md): The 'Beneficiaries' card payload: the distinct-beneficiary active count (+ % change vs the equal-length prior window) and a top-N-by-volume ranked list per currency. A pure read-model over Payout — nothing is stored. Results are scoped to the caller's Business and environment.
- [Webhook subscriptions](https://docs.usecleff.com/api-reference/webhook-subscriptions.md): Register an endpoint and receive signed, idempotent, per-Payout-ordered events from Cleff.

## OpenAPI Specs

- [openapi](/openapi.json)