Skip to main content
POST

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

Body

application/json

Create a beneficiary. Supply exactly one of individual or business matching the declared type.

type
enum<string>
required

Whether this beneficiary is a person or a business.

Available options:
individual,
business
country
string
required

ISO 3166-1 alpha-2 country code.

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

"US"

external_ref
string

Your own reference for this beneficiary. Stored as-is, not validated.

Maximum string length: 255
Example:

"contractor-1042"

metadata
object

Arbitrary string map of your own labels. Stored as-is.

Example:
individual
object

PII for an individual beneficiary. Tokenized on creation.

business
object

PII for a business beneficiary. Tokenized on creation.

end_user_ip
string

IP address of the merchant's end-user who initiated this action. Used for risk signals. Accepts IPv4 or IPv6. Optional but recommended.

Example:

"203.0.113.42"

Response

Beneficiary created.

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: