A payee is the person or business you pay. The API calls it a beneficiary, and its ID starts with ben_. A payee holds identity only. It cannot receive money until you attach an instrument to it.
Every payee belongs to one merchant. If two merchants pay the same person, each creates its own record. Personal details you send are tokenized. The payee record keeps a display name, a country and a token reference, never the raw details.
Choose the type
type decides which detail block you send. The block is named after it: individual or business. Send exactly one, matching type. country is required in both cases.
address takes street_line_1, city, postal_code and country. Add street_line_2 and state where the country needs them.
Register the payee
Creates the payee and returns it with status active. Keep the id: you need it for the instrument and the payout.
curl -X POST \ https://api.antonpayments.dev/v1/beneficiaries \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "DPoP: $DPOP_PROOF" \ -H "Idempotency-Key: ben-contractor-1042" \ -H "Content-Type: application/json" \ -d '{ "type": "individual", "country": "GB", "external_ref": "contractor-1042", "metadata": { "department": "engineering" }, "individual": { "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "phone": "+442079460000", "birth_date": "1988-05-12", "nationality": "GB", "address": { "street_line_1": "10 Example Street", "city": "London", "postal_code": "SW1A 1AA", "country": "GB" } } }'
Two fields exist for your own use. external_ref is your ID for this payee, up to 255 characters. metadata is a string map for tags such as a department. Put no personal data in either.
Add end_user_ip when a person in your product triggered the call. It is optional and feeds risk signals.
Many payees at once is a different job. Import payees from a file creates them from a CSV.
What happens next
The payee starts active. Its risk_score and risk_tier are null and risk_signals is empty until the first score, shortly after creation. Scores run from 0 to 1000 and higher is worse. Show risk_signals[].label as it comes and branch on code.
You archive and restore. Anton blocks. A blocked payee cannot be used for payouts and cannot be restored through the API.
You can ask for a fresh check of an active payee with POST /v1/beneficiaries/{id}/rescreen. It returns 202 and the payee stays active until the check finishes. If the check blocks the payee, you get a beneficiary.blocked event.
Listen for these events instead of polling: beneficiary.created, beneficiary.updated, beneficiary.blocked and beneficiary.deleted. See Track payouts with webhooks.
Find a payee you already hold
Anton refuses an identity you already hold. A second create with the same details returns 409 duplicate_beneficiary. Treat that as "already registered", not as a failure.
To find the existing record, search on your own reference:
curl "https://api.antonpayments.dev/v1/beneficiaries?search=contractor-1042" \
-H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
-H "DPoP: $DPOP_PROOF"search is a substring match on the display name and external_ref, so check the result for an exact external_ref before you reuse the ID. Store the ben_ ID next to your own record so you only search once.
Update a payee
The two update paths do different things.
PATCH /v1/beneficiaries/{id} changes display_name, country, external_ref and metadata. A field you leave out stays as it is. Send null to clear external_ref or metadata. It does not touch personal details.
PATCH /v1/beneficiaries/{id}/pii replaces the stored personal details. Vault tokens are immutable, so the block you send replaces the old one as a whole. A field you leave out is cleared, not kept. Send the complete block, even if one field changed. The display_name is re-derived from it.
Machine credentials can write personal details but cannot read them back. GET /v1/beneficiaries/{id}/pii answers 403 to an API credential. It works only for signed-in admin users of the merchant dashboard, and each read is audited. Keep your own copy of what you submit.
To stop paying someone, archive the payee. Archive keeps the record and the history, and you can restore it. Delete is for a payee you will never use again.
When it goes wrong
external_ref and use that ID.type, or a field is invalid. details lists every failing field, so fix them in one pass.ben_ ID.Idempotency
POST /v1/beneficiaries requires an Idempotency-Key. Build it from your own data, such as ben-contractor-1042, so a retry after a network failure returns the original payee. A replay carries Idempotent-Replayed: true. Keys last 24 hours, and only a 2xx answer is stored, so a refused request runs again on retry. See Idempotency.