Skip to main content
POST
/
v1
/
beneficiaries
curl --request POST \
  --url https://api.antonpayments.com/v1/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "type": "individual",
  "country": "GB",
  "external_ref": "contractor-1042",
  "individual": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "phone": "+442079460000",
    "date_of_birth": "1988-05-12",
    "nationality": "GB",
    "address": {
      "street_line_1": "10 Example Street",
      "city": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    }
  }
}
'
{
  "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_....

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:
{
  "department": "engineering",
  "cost_center": "4421"
}
​
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.

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