Skip to main content
PUT
/
v1
/
beneficiaries
/
{id}
Update a beneficiary
curl --request PUT \
  --url https://api.antonpayments.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "display_name": "<string>",
  "country": "US",
  "external_ref": "<string>",
  "metadata": {},
  "end_user_ip": "<string>"
}
'
{
  "id": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
  "merchant_id": "mer_01HX8Z9K0M2N3P4Q5R6S7T8UZZ",
  "type": "individual",
  "status": "active",
  "display_name": "Jane Smith",
  "country": "GB",
  "external_ref": "contractor-1042",
  "metadata": {
    "department": "engineering"
  },
  "created_at": "2026-04-15T14:30:00Z",
  "updated_at": "2026-04-15T14:30:00Z"
}

Authorizations

​
Authorization
string
header
required

API keys are opaque strings prefixed by environment:

  • ak_live_* — production keys, accepted only on api.antonpayments.com.
  • ak_test_* — sandbox keys, accepted only on api.antonpayments.dev.

Include your key in the Authorization header: Bearer ak_test_....

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.

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.

​
id
string
required
Pattern: ^ben_[a-zA-Z0-9]+$
Example:

"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"

​
merchant_id
string
required
Pattern: ^mer_[a-zA-Z0-9]+$
​
type
enum<string>
required
Available options:
individual,
business
​
status
enum<string>
required
  • active — usable for payouts.
  • archived — soft-disabled by the merchant; not usable. Can be restored.
  • blocked — blocked by compliance. Not usable and cannot be restored via the API.
Available options:
active,
archived,
blocked
​
display_name
string
required

Derived from the tokenized PII on creation. For individuals, a concatenation of name fields; for businesses, the legal name.

Example:

"Jane Smith"

​
country
string
required

ISO 3166-1 alpha-2 country code.

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

"US"

​
created_at
string<date-time>
required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
updated_at
string<date-time>
required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
external_ref
string | null

Your own reference, if you supplied one at creation.

​
metadata
object