Create a Beneficiary
Create a person (individual) or business (business) you want to pay. PII
submitted in the request body is tokenized in Basis Theory on creation — only
a display name, country, and opaque token reference are stored in the Anton
database.
To retrieve the PII you submitted, use GET /v1/beneficiaries/{id}/pii.
This endpoint requires an Idempotency-Key header. Duplicate calls with the
same key return the original beneficiary; different bodies with the same key
return 409 idempotency_conflict.
Authorizations
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
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.
255Body
Create a beneficiary. Supply exactly one of individual or business matching
the declared type.
Whether this beneficiary is a person or a business.
individual, business ISO 3166-1 alpha-2 country code.
^[A-Z]{2}$"US"
Your own reference for this beneficiary. Stored as-is, not validated.
255"contractor-1042"
Arbitrary string map of your own labels. Stored as-is.
PII for an individual beneficiary. Tokenized on creation.
PII for a business beneficiary. Tokenized on creation.
IP address of the merchant's end-user who initiated this action. Used for risk signals. Accepts IPv4 or IPv6. Optional but recommended.
"203.0.113.42"
Response
Beneficiary created.
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.