Update a Beneficiary

PUT

beneficiaries

{id}

Edit a Beneficiary’s profile

curl --request PUT \
  --url https://api.example.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jsmith@example.com",
  "phone": "<string>",
  "nickname": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "country_of_residence": "<string>",
  "date_of_birth": "<string>",
  "business_name": "<string>",
  "country_of_incorporation": "<string>",
  "registration_number": "<string>",
  "tax_id": "<string>",
  "postal_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://api.example.com/v1/beneficiaries/{id}"

payload = {
    "email": "jsmith@example.com",
    "phone": "<string>",
    "nickname": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "country_of_residence": "<string>",
    "date_of_birth": "<string>",
    "business_name": "<string>",
    "country_of_incorporation": "<string>",
    "registration_number": "<string>",
    "tax_id": "<string>",
    "postal_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<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({
    email: 'jsmith@example.com',
    phone: '<string>',
    nickname: '<string>',
    first_name: '<string>',
    last_name: '<string>',
    country_of_residence: '<string>',
    date_of_birth: '<string>',
    business_name: '<string>',
    country_of_incorporation: '<string>',
    registration_number: '<string>',
    tax_id: '<string>',
    postal_address: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postal_code: '<string>',
      country: '<string>'
    }
  })
};

fetch('https://api.example.com/v1/beneficiaries/{id}', 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.example.com/v1/beneficiaries/{id}",
  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([
    'email' => 'jsmith@example.com',
    'phone' => '<string>',
    'nickname' => '<string>',
    'first_name' => '<string>',
    'last_name' => '<string>',
    'country_of_residence' => '<string>',
    'date_of_birth' => '<string>',
    'business_name' => '<string>',
    'country_of_incorporation' => '<string>',
    'registration_number' => '<string>',
    'tax_id' => '<string>',
    'postal_address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postal_code' => '<string>',
        'country' => '<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.example.com/v1/beneficiaries/{id}"

	payload := strings.NewReader("{\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"nickname\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"country_of_residence\": \"<string>\",\n  \"date_of_birth\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"country_of_incorporation\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"postal_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\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.example.com/v1/beneficiaries/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"nickname\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"country_of_residence\": \"<string>\",\n  \"date_of_birth\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"country_of_incorporation\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"postal_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/beneficiaries/{id}")

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  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"nickname\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"country_of_residence\": \"<string>\",\n  \"date_of_birth\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"country_of_incorporation\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"postal_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\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": {},
  "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

string

required

Body

application/json

string<email>

required

phone

string

Optional contact phone. Non-trigger; full-replace (omitting clears it).

nickname

string

Cleff-only display label, preferred over the legal name. Non-trigger.

first_name

string

Person: given name (trigger field)

last_name

string

Person: family name (trigger field)

country_of_residence

string

Person: ISO 3166-1 alpha-2 country of residence (trigger)

date_of_birth

string

Person: date of birth YYYY-MM-DD (trigger field)

business_name

string

Business: legal business name (trigger field)

country_of_incorporation

string

Business: ISO 3166-1 alpha-2 country of incorporation (trigger)

registration_number

string

Business: Cleff-owned KYB record (trigger field)

tax_id

string

Tax identifier (trigger field)

postal_address

object

Optional mailing/legal address (omit to clear). Non-trigger.

Show child attributes

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 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

⌘I

Edit a Beneficiary’s profile

curl --request PUT \
  --url https://api.example.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jsmith@example.com",
  "phone": "<string>",
  "nickname": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "country_of_residence": "<string>",
  "date_of_birth": "<string>",
  "business_name": "<string>",
  "country_of_incorporation": "<string>",
  "registration_number": "<string>",
  "tax_id": "<string>",
  "postal_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://api.example.com/v1/beneficiaries/{id}"

payload = {
    "email": "jsmith@example.com",
    "phone": "<string>",
    "nickname": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "country_of_residence": "<string>",
    "date_of_birth": "<string>",
    "business_name": "<string>",
    "country_of_incorporation": "<string>",
    "registration_number": "<string>",
    "tax_id": "<string>",
    "postal_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<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({
    email: 'jsmith@example.com',
    phone: '<string>',
    nickname: '<string>',
    first_name: '<string>',
    last_name: '<string>',
    country_of_residence: '<string>',
    date_of_birth: '<string>',
    business_name: '<string>',
    country_of_incorporation: '<string>',
    registration_number: '<string>',
    tax_id: '<string>',
    postal_address: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postal_code: '<string>',
      country: '<string>'
    }
  })
};

fetch('https://api.example.com/v1/beneficiaries/{id}', 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.example.com/v1/beneficiaries/{id}",
  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([
    'email' => 'jsmith@example.com',
    'phone' => '<string>',
    'nickname' => '<string>',
    'first_name' => '<string>',
    'last_name' => '<string>',
    'country_of_residence' => '<string>',
    'date_of_birth' => '<string>',
    'business_name' => '<string>',
    'country_of_incorporation' => '<string>',
    'registration_number' => '<string>',
    'tax_id' => '<string>',
    'postal_address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postal_code' => '<string>',
        'country' => '<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.example.com/v1/beneficiaries/{id}"

	payload := strings.NewReader("{\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"nickname\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"country_of_residence\": \"<string>\",\n  \"date_of_birth\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"country_of_incorporation\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"postal_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\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.example.com/v1/beneficiaries/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"nickname\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"country_of_residence\": \"<string>\",\n  \"date_of_birth\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"country_of_incorporation\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"postal_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/beneficiaries/{id}")

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  \"email\": \"jsmith@example.com\",\n  \"phone\": \"<string>\",\n  \"nickname\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"country_of_residence\": \"<string>\",\n  \"date_of_birth\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"country_of_incorporation\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"postal_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  }\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": {},
  "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"
}

Basics

Reference

Update a Beneficiary

Authorizations

Path Parameters

Body

Response