Set a declared destination

PUT

beneficiaries

{id}

declared-destination

Set the destination a Beneficiary is paid to by default

curl --request PUT \
  --url https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination_id": "<string>"
}
'

import requests

url = "https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination"

payload = { "destination_id": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({destination_id: '<string>'})
};

fetch('https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'destination_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination"

	payload := strings.NewReader("{\n  \"destination_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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": {},
  "declared_destination_id": {},
  "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",
  "enrollment_failure_detail": "<string>",
  "enrollment_failure_bank_account_id": "<string>"
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

Agents: fetch this page as plain markdown at https://docs.usecleff.com/api-reference/beneficiaries-declared-destination-update.md.

Authorizations

Authorization

string

header

required

Cleff API key, created in the dashboard under Settings → API keys

Path Parameters

string

required

Body

application/json

destination_id

string

required

A destination the Beneficiary already holds, from GET /v1/beneficiaries/{id}/bank-accounts. It must be payout-usable.

Response

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

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 payout_destination link lands no identity. Either link records the destination the beneficiary chose, which is declared_destination_id and not this field.

Available options:

not_invited,

invited,

details_submitted

details_submitted_at

object | null

required

When the beneficiary completed the full_onboarding collection-link form.

declared_destination_id

object | null

required

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

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

enrollment_failure_detail

string | null

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

string | null

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.

⌘I

Set the destination a Beneficiary is paid to by default

curl --request PUT \
  --url https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination_id": "<string>"
}
'

import requests

url = "https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination"

payload = { "destination_id": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({destination_id: '<string>'})
};

fetch('https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'destination_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination"

	payload := strings.NewReader("{\n  \"destination_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecleff.com/v1/beneficiaries/{id}/declared-destination")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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": {},
  "declared_destination_id": {},
  "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",
  "enrollment_failure_detail": "<string>",
  "enrollment_failure_bank_account_id": "<string>"
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}