> ## 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.
# Set a declared destination
> Sets `declared_destination_id` to a destination the Beneficiary already holds and that can be paid: the one a payout resolves to when it names none. The Beneficiary may set it too, through a collection link; the last write wins. Idempotent: naming the current declaration changes nothing. A change the Business makes is announced to the Beneficiary by email. Returns the Beneficiary.
**Agents:** fetch this page as plain markdown at
`https://docs.usecleff.com/api-reference/beneficiaries-declared-destination-update.md`.
## OpenAPI
````yaml PUT /v1/beneficiaries/{id}/declared-destination
openapi: 3.0.0
info:
title: Cleff API
description: >-
Payout orchestration platform. All endpoints under /v1/ require an API key
in the Authorization header (Bearer ck___).
version: 0.0.1
contact: {}
servers:
- url: https://api.usecleff.com
security: []
tags: []
paths:
/v1/beneficiaries/{id}/declared-destination:
put:
tags:
- Beneficiaries
summary: Set the destination a Beneficiary is paid to by default
description: >-
Sets `declared_destination_id` to a destination the Beneficiary already
holds and that can be paid: the one a payout resolves to when it names
none. The Beneficiary may set it too, through a collection link; the
last write wins. Idempotent: naming the current declaration changes
nothing. A change the Business makes is announced to the Beneficiary by
email. Returns the Beneficiary.
operationId: BeneficiariesController_declareDestination
parameters:
- name: id
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeclareDestinationDto'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryDto'
'400':
description: The request body failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: validation_failed
message: Request validation failed
request_id: req_abc123
occurred_at: '2026-07-07T12:00:00.000Z'
actor:
user_id: usr_...
membership_id: mem_...
role: business_admin
environment: sandbox
details:
- field: destination_id
code: invalid_uuid
message: destination_id must be a UUID
docs_url: https://docs.usecleff.com/errors#validation_failed
'401':
description: The API key is missing, invalid or revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: unauthorized
message: Unauthorized
request_id: req_abc123
occurred_at: '2026-07-07T12:00:00.000Z'
actor: null
docs_url: https://docs.usecleff.com/errors#unauthorized
'403':
description: The API key's role cannot make this request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: forbidden
message: Forbidden resource
request_id: req_abc123
occurred_at: '2026-07-07T12:00:00.000Z'
actor:
user_id: usr_...
membership_id: mem_...
role: business_read_only
environment: sandbox
docs_url: https://docs.usecleff.com/errors#forbidden
'404':
description: >-
No such Beneficiary (`not_found`), or no such destination for it
(`BANK_ACCOUNT_NOT_FOUND`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: BANK_ACCOUNT_NOT_FOUND
message: BankAccount 9b2f4c1e-5d7a-4e8b-a3c6-1f0d2e4b6a8c not found
request_id: req_abc123
occurred_at: '2026-07-07T12:00:00.000Z'
actor:
user_id: usr_...
membership_id: mem_...
role: business_admin
environment: sandbox
docs_url: https://docs.usecleff.com/errors#bank_account_not_found
'422':
description: >-
The destination cannot be paid, and the code names the check it
fails, or the Beneficiary is archived.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: BANK_ACCOUNT_NOT_VALIDATED
message: >-
bank_account routing details are not validated; cannot be a
Payout destination
request_id: req_abc123
occurred_at: '2026-07-07T12:00:00.000Z'
actor:
user_id: usr_...
membership_id: mem_...
role: business_admin
environment: sandbox
docs_url: https://docs.usecleff.com/errors#bank_account_not_validated
'429':
description: Too many requests for this Business and environment.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: RATE_LIMITED
message: Rate limit exceeded. Slow down and retry after the window.
request_id: req_abc123
occurred_at: '2026-07-07T12:00:00.000Z'
actor: null
docs_url: https://docs.usecleff.com/errors#rate_limited
security:
- api_key: []
components:
schemas:
DeclareDestinationDto:
type: object
properties:
destination_id:
type: string
description: >-
A destination the Beneficiary already holds, from `GET
/v1/beneficiaries/{id}/bank-accounts`. It must be payout-usable.
required:
- destination_id
BeneficiaryDto:
type: object
properties:
id:
type: string
beneficiary_type:
type: string
enum:
- person
- business
name:
type: string
description: Legal display name (first+last or business name); never piped
nickname:
type: object
description: Business-facing display label, when set
nullable: true
display_name:
type: string
description: 'Preferred display label: nickname when set, else legal name'
email:
type: string
phone:
type: object
nullable: true
first_name:
type: object
nullable: true
last_name:
type: object
nullable: true
country_of_residence:
type: object
nullable: true
date_of_birth:
type: object
nullable: true
business_name:
type: object
nullable: true
country_of_incorporation:
type: object
nullable: true
registration_number:
type: object
nullable: true
tax_id:
type: object
nullable: true
postal_address:
nullable: true
description: Optional structured postal address; null when unset
allOf:
- $ref: '#/components/schemas/PostalAddressDto'
bank_details:
nullable: true
deprecated: true
allOf:
- $ref: '#/components/schemas/BankDetailsDto'
compliance_status:
type: string
enum:
- pending
- compliant
- suspended
identity_complete:
type: boolean
description: >-
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:
type: object
format: date-time
nullable: true
reacknowledgment_required:
type: boolean
description: >-
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:
type: string
enum:
- not_invited
- invited
- details_submitted
description: >-
Identity collection sub-state. Only a full_onboarding link advances
it; a payout_destination link lands no identity. Either link records
the destination the beneficiary chose, which is
`declared_destination_id` and not this field.
details_submitted_at:
type: object
format: date-time
nullable: true
description: >-
When the beneficiary completed the full_onboarding collection-link
form.
declared_destination_id:
type: object
format: uuid
nullable: true
description: >-
The destination a payout goes to when it names none: the one the
beneficiary chose in the collection flow, or the one the Business
set with `PUT /v1/beneficiaries/{id}/declared-destination`,
whichever was written last. Cleff never substitutes a sibling for
it. null while none has been declared, in which case a destination
resolves only while exactly one is payout-usable and is otherwise
refused as ambiguous.
status:
type: string
enum:
- suspended
- reacknowledgment_required
- pending_details
- pending_kyc
- action_required
- ready
description: >-
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.
enrollment_status:
type: string
enum:
- pending
- verified
- rejected
- suspended
- closed
nullable: true
description: >-
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.
enrollment_failure_detail:
type: string
nullable: true
description: >-
The payment rail's own words for the refusal behind
`enrollment_status: rejected`, stripped of the provider; null in
every other enrollment state, a retry still in flight included.
Beneficiary-level: a refusal that named a bank account repeats it on
that account's `rail_rejection_reason`, while one that named none —
a person-level refusal, or a Beneficiary with no destination yet —
is readable only here.
enrollment_failure_bank_account_id:
type: string
nullable: true
description: >-
The bank account the refusal behind `enrollment_status: rejected`
named, or null when it named none (a person-level refusal, or one
that landed before any destination existed) and in every other
enrollment state. A named account repeats the same reason on its own
`rail_rejection_reason`; an unnamed one is readable only on
`enrollment_failure_detail`.
pending_requests:
description: >-
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.
type: array
items:
$ref: '#/components/schemas/PendingCollectionRequestDto'
archived_at:
type: object
format: date-time
nullable: true
description: >-
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:
type: string
enum:
- sandbox
- production
created_at:
type: string
format: date-time
required:
- id
- beneficiary_type
- name
- display_name
- email
- compliance_status
- identity_complete
- acknowledged_at
- reacknowledgment_required
- collection_status
- details_submitted_at
- declared_destination_id
- status
- pending_requests
- archived_at
- environment
- created_at
ErrorEnvelope:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorBody'
required:
- error
PostalAddressDto:
type: object
properties:
line1:
type: string
description: Street address line 1 (required when an address is present)
line2:
type: string
description: Street address line 2 (suite, unit, etc.)
city:
type: string
description: City / locality (required when an address is present)
state:
type: string
description: State / province / region
postal_code:
type: string
description: Postal / ZIP code
country:
type: string
description: >-
ISO 3166-1 alpha-2 mailing country (required when an address is
present)
BankDetailsDto:
type: object
properties:
account_holder_name:
type: string
country:
type: string
description: ISO 3166-1 alpha-2 of the bank country
currency:
type: string
description: ISO 4217 currency code
account_number:
type: string
description: Domestic account number (US/JP/etc.)
routing_code:
type: string
description: US ABA, UK sort code, BR branch_code, etc.
iban:
type: string
description: IBAN — required for European corridors
swift_bic:
type: string
description: SWIFT/BIC — required for cross-border SWIFT routing
bank_name:
type: string
required:
- account_holder_name
- country
- currency
PendingCollectionRequestDto:
type: object
properties:
id:
type: string
format: uuid
description: >-
Collection-token id (safe to expose; the raw token is never
serialized).
scope:
type: string
enum:
- full_onboarding
- payout_destination
- tax_documents
description: What the live link collects.
expires_at:
type: string
format: date-time
description: Token TTL expiry (7 days from mint).
required:
- id
- scope
- expires_at
ErrorBody:
type: object
properties:
code:
type: string
message:
type: string
request_id:
type: string
occurred_at:
type: string
format: date-time
actor:
nullable: true
allOf:
- $ref: '#/components/schemas/ErrorActor'
details:
type: array
items:
$ref: '#/components/schemas/ErrorDetail'
docs_url:
type: string
required:
- code
- message
- request_id
- occurred_at
- actor
- docs_url
ErrorActor:
type: object
properties:
user_id:
type: string
membership_id:
type: string
role:
type: string
environment:
type: string
enum:
- sandbox
- production
required:
- user_id
- membership_id
- role
- environment
ErrorDetail:
type: object
properties:
field:
type: string
code:
type: string
message:
type: string
required:
- field
- code
- message
securitySchemes:
api_key:
scheme: bearer
bearerFormat: ck___
type: http
description: Cleff API key, created in the dashboard under Settings → API keys
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.