Skip to main content
PUT
Update a beneficiary

Authorizations

DPoP
string
header
required

Per-request DPoP proof JWT (RFC 9449). MUST accompany the Authorization: DPoP <access_token> header on every protected operation. The proof is signed by the merchant's private DPoP key and carries htm, htu, iat, jti, and ath claims.

Headers

Idempotency-Key
string
required

Unique key identifying this operation. Sending the same key twice returns the original response instead of creating a duplicate. Keys are retained for 24 hours.

Maximum string length: 255

Path Parameters

id
string
required

Beneficiary ID (prefixed ben_).

Pattern: ^ben_[a-zA-Z0-9]+$
Example:

"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"

Body

application/json

Mutable fields on a beneficiary. Fields not included are left unchanged.

display_name
string
Maximum string length: 255
country
string

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$
Example:

"US"

external_ref
string | null

Set to null to clear.

Maximum string length: 255
metadata
object

Replaces the existing metadata map in full.

end_user_ip
string

Response

Beneficiary updated.

data
object
required

A person or business you pay. PII is tokenized in Basis Theory on creation — raw identifiers are never returned in this response. Use GET /v1/beneficiaries/{id}/pii to retrieve detokenized PII for a beneficiary you own.

Example: