Replace Beneficiary PII
Replaces the PII stored in Basis Theory for this beneficiary. The entire PII blob is replaced — partial updates are not supported, because tokens are immutable.
Supply the detail block matching the beneficiary’s type (individual or
business). The display_name on the beneficiary record is automatically
re-derived from the new PII.
Authorizations
OAuth 2.0 client_credentials grant (RFC 6749 §4.4) bound to a DPoP keypair (RFC 9449).
Flow (every authenticated /v1 call requires both an access token AND a fresh per-request DPoP proof):
- Register a credential via the merchant portal. Anton issues a
client_id(ant_oc_<env>_<32hex>) and aclient_secret(ant_ocs_<env>_<48hex>, shown ONCE). The portal generates an ES256 or Ed25519 DPoP keypair in your browser; you store the private half. - Mint an access token:
POST /oauth/tokenwithAuthorization: Basic <client_id:client_secret>andContent-Type: application/x-www-form-urlencoded. Body:grant_type=client_credentials. ADPoPheader carrying a proof signed for the token endpoint is required (noathclaim on this proof). - Use the token: send
Authorization: DPoP <access_token>plus a freshDPoP: <proof>header on every/v1request. The proof JWT MUST carryhtm(request method),htu(request URL, no query/fragment),iat(within ±60s),jti(unique within 5 min), andath(SHA-256 of the access token, base64url).
Tokens expire in 1 hour in production / staging and 8 hours in sandbox. There are no refresh tokens — call /oauth/token again with your secret. Anton's public signing key is published at /.well-known/jwks.json.
OpenAPI 3.0 has no native DPoP scheme; this declaration plus dpopHeader together convey both the access-token Authorization and the per-request proof header.
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.
Path Parameters
^ben_[a-zA-Z0-9]+$Body
Replacement PII. Provide the detail block matching the beneficiary's type. The entire PII blob is replaced — partial updates are not supported.
Response
Beneficiary PII replaced. Returns the updated beneficiary record.
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.
^ben_[a-zA-Z0-9]+$"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"
^mer_[a-zA-Z0-9]+$individual, business 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.
active, archived, blocked Derived from the tokenized PII on creation. For individuals, a concatenation of name fields; for businesses, the legal name.
"Jane Smith"
ISO 3166-1 alpha-2 country code.
^[A-Z]{2}$"US"
RFC 3339 / ISO 8601 timestamp in UTC.
"2026-04-15T14:30:00Z"
RFC 3339 / ISO 8601 timestamp in UTC.
"2026-04-15T14:30:00Z"
Your own reference, if you supplied one at creation.