Onboard a Beneficiary

Onboard a Beneficiary and leave them ready to be paid. For developers wiring onboarding into their product. Every path below onboards the same Beneficiary (the payee), Jane Doe, and ends with her status reading ready.

Agents: fetch this page as plain markdown at https://docs.usecleff.com/guides/onboard-a-beneficiary.md.

You need a sandbox API key exported as CLEFF_API_KEY; the Quickstart shows how to mint one. What ready means, and which destination a payout to Jane goes to, is on Beneficiaries & compliance.

Pick a path

You hold	Path	Jane’s destination
Jane’s verified identity and bank details	Register Jane through the API	The bank account you register
The same, for Jane and many others	Import Jane with the rest of your base	The bank account in her row
Jane’s name and email address	Invite Jane to enter her own details	The bank account or card she chooses

Pick one path per Beneficiary. An email address belongs to one active Beneficiary per environment, so creating Jane a second time with jane@example.com is refused.

Register Jane through the API

Create Jane and attest to her compliance

Passing acknowledged: true records that your Business has independently verified Jane’s identity, which makes her compliant straight away.

curl -X POST https://api.usecleff.com/v1/beneficiaries \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_type": "person",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "country_of_residence": "US",
    "acknowledged": true
  }'

Capture beneficiary.id from the response:

export BEN_ID="<beneficiary.id>"

Jane’s status is now action_required: she is compliant but has nowhere to be paid.

curl -X POST https://api.usecleff.com/v1/beneficiaries/$BEN_ID/bank-accounts \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_holder_name": "Jane Doe",
    "country": "US",
    "currency": "USD",
    "account_number": "000123456789",
    "routing_code": "021000021"
  }'

{
  "bank_account": {
    "id": "8d6f3c2a-51b7-4e0f-9a3d-7c1e2b4f6a90",
    "kind": "bank",
    "account_holder_name": "Jane Doe",
    "currency": "USD",
    "country": "US",
    "status": "verified",
    "validation_status": "validated",
    "payout_usable": true,
    "rail_rejection_reason": null,
    "last4": "6789",
    "account_type": null
  }
}

Because Jane is already compliant, the account is verified on arrival, and a routing number that passes Cleff’s format checks makes it validated. Together they give payout_usable: true.

Jane holds one destination and has declared none, so a payout that omits destination_id goes to this account. Confirm she is ready.

Import Jane with the rest of your base

Import creates each Beneficiary, registers their bank account and records your attestation in one request, for up to 500 rows. Every row needs acknowledged: true, and the call needs a key with the business_admin role.

curl -X POST https://api.usecleff.com/v1/beneficiaries/import \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "beneficiary_type": "person",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "country_of_residence": "US",
        "acknowledged": true,
        "bank": {
          "account_holder_name": "Jane Doe",
          "country": "US",
          "currency": "USD",
          "account_number": "000123456789",
          "routing_code": "021000021"
        }
      }
    ]
  }'

{
  "results": [
    {
      "index": 0,
      "status": "created",
      "beneficiary_id": "3b9e1f4c-2a6d-4c8e-b1f0-5d7a9c3e2b18",
      "bank_account_id": "8d6f3c2a-51b7-4e0f-9a3d-7c1e2b4f6a90",
      "payout_usable": true
    }
  ],
  "created_count": 1,
  "failed_count": 0
}

Jane’s row was created, and payout_usable: true means her account can be paid already. A row can be created with payout_usable: false; the reference explains per-row failures and what to resend.

export BEN_ID="<results[0].beneficiary_id>"

Confirm she is ready.

Invite Jane to enter her own details

Inviting keeps Jane’s identity details and account number out of your systems, and it is the only path on which she can choose a debit card or pick which destination she is paid to.

Invite her

Bulk invites create an identity-only Beneficiary per row and email each one a link to a form where they enter their own details.

curl -X POST https://api.usecleff.com/v1/beneficiaries/bulk-invites \
  -H "Authorization: Bearer $CLEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "beneficiary_type": "person",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com"
      }
    ]
  }'

{
  "invited": [
    {
      "index": 0,
      "id": "3b9e1f4c-2a6d-4c8e-b1f0-5d7a9c3e2b18",
      "email": "jane@example.com"
    }
  ],
  "failed": []
}

export BEN_ID="<invited[0].id>"

Jane’s status is pending_details until she submits the form.

Wait for her to submit

Jane fills in her identity details and adds a destination: a bank account, or, in production, a debit card if your Business is approved for card payouts. The destination she adds becomes her declared destination.Subscribe to beneficiary.details_submitted to hear when she is done, or poll her until her status moves from pending_details to pending_kyc:

curl https://api.usecleff.com/v1/beneficiaries/$BEN_ID \
  -H "Authorization: Bearer $CLEFF_API_KEY"

Once it reads pending_kyc, her details are in, and they wait on your attestation.

Attest to her compliance

Check the identity Jane submitted, then acknowledge it:

curl -X POST https://api.usecleff.com/v1/beneficiaries/$BEN_ID/compliance-acknowledgment \
  -H "Authorization: Bearer $CLEFF_API_KEY"

Jane becomes compliant, and the destination she added is verified with her.

Confirm Jane is ready to pay

Whichever path you took, read Jane back:

curl https://api.usecleff.com/v1/beneficiaries/$BEN_ID \
  -H "Authorization: Bearer $CLEFF_API_KEY"

{
  "id": "3b9e1f4c-2a6d-4c8e-b1f0-5d7a9c3e2b18",
  "beneficiary_type": "person",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "compliance_status": "compliant",
  "reacknowledgment_required": false,
  "declared_destination_id": "8d6f3c2a-51b7-4e0f-9a3d-7c1e2b4f6a90",
  "status": "ready",
  "environment": "sandbox"
}

The response is trimmed to the fields that matter here. Read two of them:

Field	Expect	Recovery
`status`	`ready`	Find the value in the status table and follow its Recovery.
`declared_destination_id`	The destination Jane chose if you invited her; `null` if you registered or imported her	Nothing to fix. With `null`, a payout goes to her one destination, or to the one you name.

Jane is ready to pay. A payout to her needs only beneficiary_id: with a declared destination it goes there, and without one it goes to the only destination she holds.

Get started

Essentials

Beneficiaries

Payouts

Onboard a Beneficiary

Pick a path

Register Jane through the API

Import Jane with the rest of your base

Invite Jane to enter her own details

Confirm Jane is ready to pay

​Pick a path

​Register Jane through the API

​Import Jane with the rest of your base

​Invite Jane to enter her own details

​Confirm Jane is ready to pay

Pick a path

Register Jane through the API

Import Jane with the rest of your base

Invite Jane to enter her own details

Confirm Jane is ready to pay