Anton.Docs
Dashboard (opens in a new tab)
API referenceVerifications

Create a verification subject

POST/v1/verification-subjectsIdempotency-Key required

Walked through inVerify a person or business

Example

Create a verification subject (a person or a business) and open its first verification. The response is the subject, with that verification in verifications carrying the one-time hosted_link. Anton mints a hosted verification link, a one-time identity verification flow. A person submits a government ID and selfie. A business submits business details plus a UBO cascade. Identity documents live with the verification provider and Anton's vault; they never touch your systems.

Link delivery. With delivery: "email", Anton emails the link to the subject and the verification is created with status sent. If the environment cannot deliver email, or you choose delivery: "manual", the status is created and YOU deliver the returned hosted_link through your own channel. Only trust sent as proof an email went out.

hosted_link is secret-once. It appears in this response (and on resend, regenerate and re-verify responses) and is never readable again. Treat it like a credential: it opens a flow that collects your customer's identity documents.

Track progress through the verification.* webhook events or by polling the subject. You need the intelligence credential scope and account capability.

Headers

Anton-Versionstring

The API version for this request, a date such as 2026-12-01. Optional. Without it, the request runs on your account's pinned version: the latest version when you created your first OAuth client, or the launch version (2026-12-01) if you have not created one. An unknown value returns 400 invalid_api_version. The header applies to one request and never changes your pinned version; move the pin from the dashboard. It does not apply to webhooks, which follow your pinned version. The response echoes the version used in the Anton-Version header.

Example: "2026-12-01"
Idempotency-Keystring · 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.

Body application/json

typestring · required
personbusiness
display_namestring · required

The subject's legal name. Vault-tokenized at rest; masked on every read.

emailstring

Where the hosted link is delivered (with delivery: "email"), and the address shown in the flow. Without an email on file, delivery cannot happen: the verification stays created and you deliver the link yourself.

external_refstring

Optional identifier from your systems, echoed back on reads.

countrystring

ISO 3166-1 alpha-2. Recommended; it feeds sanctions screening disambiguation.

deliverystring

email: Anton emails the hosted link to the subject. manual (the default when omitted): you deliver the returned hosted_link yourself.

emailmanual
messagestring

Optional text shown in the delivery email, attributed to your business. Used for that one send and never persisted (it may carry incidental PII); it cannot be read back.

link_expires_in_daysinteger

Hosted-link lifetime.

71430
metadataobject

Your own key/value pairs, stored and returned as-is. At most 50 keys; keys up to 40 characters and values up to 500, all strings. On a beneficiary the key block_reason is reserved and is refused with 422. Anton never reads it, never logs or audits it, and never sends it to screening or risk checks, so it is not searchable. Never put personal data in it.

Do not store personal information, account numbers or credentials in metadata. Use the resource's own fields, which are tokenized.

Responses

201Subject created; its first verification opened.
idstring · required

Subject ID (vsub_...).

objectstring · required
verification_subject
livemodeboolean · required
statusstring · required

Where a verification attempt stands.

  • created: the attempt exists and the link is minted, but nothing is delivered yet (manual delivery, or email unavailable)
  • sent: the hosted link was delivered to the subject by email
  • in_progress: the subject opened the flow
  • processing: submitted, and provider checks are running
  • awaiting_owners: business only. The business case is done and owner (UBO) flows are outstanding
  • review: flagged for manual review
  • approved: verified (terminal)
  • declined: failed verification (terminal)
  • expired: the link or inquiry lapsed unused (terminal)
  • revoked: cancelled by the merchant (terminal)
createdsentin_progressprocessingawaiting_ownersreviewapproveddeclinedexpiredrevoked
typestring · required
personbusiness
display_namestring · required

Masked display name.

emailstring · required

Masked (a***@example.com); empty when the subject has no email; the fixed value unavailable when the stored address could not be read. The full address is available only to people with the identity-details permission, in the portal.

external_refstring | null · required

Your identifier for this subject, echoed back verbatim.

countrystring · required

ISO 3166-1 alpha-2.

current_verification_idstring | null · required
metadataobject · required

Your own key/value pairs, stored and returned as-is. At most 50 keys; keys up to 40 characters and values up to 500, all strings. On a beneficiary the key block_reason is reserved and is refused with 422. Anton never reads it, never logs or audits it, and never sends it to screening or risk checks, so it is not searchable. Never put personal data in it.

Do not store personal information, account numbers or credentials in metadata. Use the resource's own fields, which are tokenized.

created_atstring (date-time) · required

RFC 3339 / ISO 8601 timestamp in UTC.

Example: "2026-04-15T14:30:00Z"
updated_atstring (date-time) · required

RFC 3339 / ISO 8601 timestamp in UTC.

Example: "2026-04-15T14:30:00Z"
verificationsarray of object
Item fields (14)
idstring · required

Verification ID (vrf_...).

objectstring · required
verification
livemodeboolean · required
statusstring · required

Where a verification attempt stands.

  • created: the attempt exists and the link is minted, but nothing is delivered yet (manual delivery, or email unavailable)
  • sent: the hosted link was delivered to the subject by email
  • in_progress: the subject opened the flow
  • processing: submitted, and provider checks are running
  • awaiting_owners: business only. The business case is done and owner (UBO) flows are outstanding
  • review: flagged for manual review
  • approved: verified (terminal)
  • declined: failed verification (terminal)
  • expired: the link or inquiry lapsed unused (terminal)
  • revoked: cancelled by the merchant (terminal)
createdsentin_progressprocessingawaiting_ownersreviewapproveddeclinedexpiredrevoked
subject_idstring · required
reasonstring · required

Why this verification was opened.

initialreverificationregenerated
screeningobject | null · required

null until the verification has been screened.

ownersarray of object · required

Business verifications only; empty otherwise.

Item fields (8)
idstring · required

Owner ID (vubo_...).

objectstring · required
verification_owner
livemodeboolean · required
statusstring · required

Where a verification attempt stands.

  • created: the attempt exists and the link is minted, but nothing is delivered yet (manual delivery, or email unavailable)
  • sent: the hosted link was delivered to the subject by email
  • in_progress: the subject opened the flow
  • processing: submitted, and provider checks are running
  • awaiting_owners: business only. The business case is done and owner (UBO) flows are outstanding
  • review: flagged for manual review
  • approved: verified (terminal)
  • declined: failed verification (terminal)
  • expired: the link or inquiry lapsed unused (terminal)
  • revoked: cancelled by the merchant (terminal)
createdsentin_progressprocessingawaiting_ownersreviewapproveddeclinedexpiredrevoked
display_namestring · required

Masked owner name.

emailstring · required

Masked (m***@example.com). The full address is available only to people with the identity-details permission, in the portal.

ownership_percentageinteger · required

Declared ownership percentage.

completed_atstring (date-time) | null · required

Set once the owner's flow reached a terminal outcome.

link_expires_atstring (date-time) | null · required

When the current hosted link lapses.

completed_atstring (date-time) | null · required

Set once the verification reached a terminal outcome.

metadataobject · required

Your own key-value pairs for this verification, set in the body when you re-verify a subject. Returned as-is and never read by Anton. The first verification of a subject carries none; set metadata on the subject when you create it.

created_atstring (date-time) · required

RFC 3339 / ISO 8601 timestamp in UTC.

Example: "2026-04-15T14:30:00Z"
updated_atstring (date-time) · required

RFC 3339 / ISO 8601 timestamp in UTC.

Example: "2026-04-15T14:30:00Z"
hosted_linkstring | null

Secret-once hosted verification link. Present only on the response that minted it. A replay of that request (same Idempotency-Key) returns the same resource with hosted_link null: the link is returned once and never stored. Call regenerate to get a new link.

400The request body could not be parsed or contains unknown fields, its `Content-Type` is not `application/json` (`invalid_content_type`), or t
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
401Missing, expired or invalid credentials (access token or DPoP proof). Carries `WWW-Authenticate`.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
403The account capability or credential scope the call needs is missing.

The account capability or credential scope the call needs is missing.

capability_required: the merchant account does not hold the required capability (for example, an AI-compliance-only account calling a payout endpoint). insufficient_scope: the account holds it, but this credential was created without the matching scope. Effective access is always scopes ∩ capabilities. A sandbox credential used against production is key_environment_mismatch.

errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
409`idempotency_in_flight`: another request with the same `Idempotency-Key` is still being processed. Retry after it completes, and the complet
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
422`validation_error` (every failing field is listed in `details`) or `idempotency_key_reused`.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
detailsarray of object · required

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
429Rate limit exceeded. See `Retry-After`. The `X-RateLimit-*` headers are on every authenticated API response, not only on 429s; they are docu
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
500Something went wrong on our end (`api_error`: 500 `internal_error`, 502 `upstream_error`, 503 `service_unavailable`). The message is always
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
503The verification provider is not configured on this environment.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).

authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗