Acknowledge compliance

Idempotent. Promotes pending → compliant on first attestation and clears the reacknowledgment_required soft flag on subsequent ones. Returns the updated Beneficiary.

POST /v1/beneficiaries/{id}/compliance-acknowledgment

Acknowledge (or re-acknowledge) a Beneficiary’s compliance

cURL

curl --request POST \
  --url https://api.example.com/v1/beneficiaries/{id}/compliance-acknowledgment \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "<string>",
  "beneficiary_type": "person",
  "name": "<string>",
  "display_name": "<string>",
  "email": "<string>",
  "compliance_status": "pending",
  "identity_complete": true,
  "acknowledged_at": {},
  "reacknowledgment_required": true,
  "collection_status": "not_invited",
  "details_submitted_at": {},
  "status": "suspended",
  "pending_requests": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scope": "full_onboarding",
      "expires_at": "2023-11-07T05:31:56Z"
    }
  ],
  "archived_at": {},
  "environment": "sandbox",
  "created_at": "2023-11-07T05:31:56Z",
  "nickname": {},
  "phone": {},
  "first_name": {},
  "last_name": {},
  "country_of_residence": {},
  "date_of_birth": {},
  "business_name": {},
  "country_of_incorporation": {},
  "registration_number": {},
  "tax_id": {},
  "postal_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "bank_details": {
    "account_holder_name": "<string>",
    "country": "<string>",
    "currency": "<string>",
    "account_number": "<string>",
    "routing_code": "<string>",
    "iban": "<string>",
    "swift_bic": "<string>",
    "bank_name": "<string>"
  },
  "enrollment_status": "pending"
}

Authorizations

Authorization · string · header · required

Cleff API key issued to a Business that self-registers via POST /v1/registration

Path Parameters

id · string · required

Response

200

application/json

id · string · required

beneficiary_type · enum<string> · required

Available options: person, business

name · string · required

Legal display name (first+last or business name); never piped

display_name · string · required

Preferred display label: nickname when set, else legal name

email · string · required

compliance_status · enum<string> · required

Available options: pending, compliant, suspended

identity_complete · boolean · required

Derived: false while the per-type required identity field is still deferred (a stub in the awaiting_pii state). True once the identity is complete. Never stored. Computed against the CURRENT required-field list, so a compliant beneficiary can read false after that list grows: that is a top-up prompt, not a block — the beneficiary keeps its status and keeps receiving payouts, and supplying the field on PUT /v1/beneficiaries/:id or over a full_onboarding collect link flips it back to true.

acknowledged_at · object | null · required

reacknowledgment_required · boolean · required

Soft flag: a trigger PII field changed after acknowledgment. Compliance status stays compliant, but new Payout creation is blocked until the Business re-acknowledges.

collection_status · enum<string> · required

Identity collection sub-state. Only a full_onboarding link advances it — a bank_details link never touches the Beneficiary.

Available options: not_invited, invited, details_submitted

details_submitted_at · object | null · required

When the beneficiary completed the full_onboarding collection-link form.

status · enum<string> · required

Derived read-model Status chip: a pure projection over {identity completeness, compliance state + re-ack flag, bank-account validation/verification}. The invited chip was retired. Not a stored state machine.

Available options: suspended, reacknowledgment_required, pending_details, pending_kyc, action_required, ready

pending_requests · object[] · required

Derived: the beneficiary's live (unconsumed, unexpired) collection-link requests — {id, scope, expires_at} — read off the live-token store, never stored. Consumed/expired tokens never appear. Cardinality is 0..1 today (resend invalidates the prior link), but the shape is a list.

Show child attributes

archived_at · object | null · required

When the Business archived this Beneficiary, or null while it is active. An archived Beneficiary is gone from the address book (list, CSV export) and refuses new Payouts, but stays readable by id so a Payout's payee can still be resolved.

environment · enum<string> · required

Available options: sandbox, production

created_at · string<date-time> · required

nickname · object | null

Business-facing display label, when set

phone · object | null

first_name · object | null

last_name · object | null

country_of_residence · object | null

date_of_birth · object | null

business_name · object | null

country_of_incorporation · object | null

registration_number · object | null

tax_id · object | null

postal_address · object | null

Optional structured postal address; null when unset

Show child attributes

bank_details · object | null · deprecated

Show child attributes

enrollment_status · enum<string> | null

Provider enrollment status for the default payout rail, or null when the Beneficiary has never been enrolled. rejected means the last synchronous enrollment attempt failed (e.g. the rail rejected the bank): the Beneficiary is compliant but payouts cannot reach them until re-enrollment succeeds.

Available options: pending, verified, rejected, suspended, closed