Verification & Endorsements

The model

The endorsement is the verification. You request an endorsement by name (endo_usd for USD services), and the review of the customer for that currency is the whole verification. There is no separate identity check in front of it. Everything, from progress to asks to approval to adverse decisions, surfaces on that endorsement's status and requirements.

You share everything over the API. Profile fields, identity documents, and supporting documents ride the customer object on create and PATCH. We hold them, and nothing is reviewed until you submit. See Customers.

Each submission opens one verification round (ver_...) per endorsement it sends to review. Rounds are history. Build your UI on the endorsement.

Documents we ask for

We ask up front for every document the review needs. Once you request an endorsement, its missing bucket lists each document still owed, so you can collect them all before you submit. The submit returns 422 verification_incomplete while any is owed. Each code below is also the purpose you send the document under (see Customers), except identity, which rides identifying_information, and the controller_ codes, which ride each controller's own identifying_information and documents.

Individuals

Businesses, by legal form (business_kind):

Every business also owes, for each controller, an identity document (controller_identity) and a proof of address (controller_proof_of_address).

To see a business's whole list from the start, send business_kind when you create it. Without it, missing names registration_document first, and the rest of the list appears once the submit reads the legal form from that document.

What each business document is:

These are the documents every customer of a kind or legal form needs. The review can ask one customer for more, for example under enhanced due diligence. Those asks arrive in the requirement buckets like any other, and each has its own purpose:

Submitting for review

The first submission is explicit. Its body takes an optional intake_method, which says how the customer's details and documents reach us:

An empty body is the same as {"intake_method": "api"}:

curl -s $BASE/api/customers/cus_.../verifications \
  -H "Api-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{}'

redirect_url belongs to hosted collection only. Sent without "intake_method": "hosted", it returns 422 invalid_parameter. Any other field, requested_info included, also returns 422 invalid_parameter. The response is a list with one round for each endorsement the call sent to review:

{
  "data": [
    {
      "id": "ver_033y1FhTOmoW9W2jAuSvQx",
      "object": "verification",
      "customer_id": "cus_033y1FhTOmoW9W2jAuSvQx",
      "endorsement": "endo_usd",
      "purpose": "full",
      "requested_info": null,
      "intake_method": "api",
      "status": "under_review",
      "url": null,
      "expires_at": null,
      "rejection_reasons": null,
      "created_at": "2026-08-26T09:15:32+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

A submit sends every requested endorsement that is incomplete or in issues. Endorsements already under review or decided are left alone.

Documents are read at submit

Send the images, and we read the rest. At submit we read the newest document of each kind below, for the customer and for each controller of a business, then fill the fields you left empty. Selfies are not read, and neither are the business documents that carry no profile field (articles_of_association, operating_agreement, ownership_information, and proof_of_signatory_authority).

A controller's identity document, proof of address, and proof of tax identification fill that person's fields the same way. A value you sent is never overwritten. It changes only through your own PATCH. Only what the documents could not supply is asked, in missing and in the submit's 422 verification_incomplete.

Each document is read once, and a newer document's reading replaces a value an older one filled. An address always comes from one document, so lines from two documents never mix. We read identity and registration documents first, so a proof of address or a tax document is checked against the name they carry, or the name you sent.

Contact data appears on no document, so requesting endo_usd needs it already on the customer or in the same request: email and phone for an individual, or email for a business. Missing ones return 422 endorsement_profile_required.

Tax data is not needed to request endo_usd, but the review needs it. In live, until you send tax_id, and tax_residence_country for an individual, or a proof_of_tax_identification that carries them, the endorsement lists them in missing and the submit's 422 verification_incomplete names them. Send them on create so the first submit is not held up.

A document we cannot accept is asked for again

Reading also checks the document. When the newest document for a requirement has one of these problems, that requirement moves to the issues bucket and the submit returns 422 verification_incomplete before anything is sent to review:

The message names the document and the problem:

{
  "error": {
    "kind": "invalid_request_error",
    "code": "verification_incomplete",
    "message": "The proof of address was not accepted: it is older than we accept. Supply them via POST /api/customers or PATCH /api/customers/{id}, then submit.",
    "param": "proof_of_address",
    "request_id": "req_033xhsr1AZZxC8AOkK7y3W"
  }
}

Supply a new document with a PATCH, then submit. After the first submit, the same check runs on every PATCH that resubmits: a document we cannot accept is listed in issues, and nothing is sent to review until it is replaced.

After the first submit

You do not submit again to send a change. A PATCH that changes something resubmits by itself: a new document, a corrected value, or a newly requested endorsement. Every endorsement that is incomplete or in issues and owes nothing goes back to review in a new resubmission round, and the PATCH response shows the outcome.

• A PATCH that changes nothing does nothing. The same file again or the same value again opens no round. Files are deduplicated by content hash, so send a new image when a document was refused.
• A document added after approval is held, not sent. It shows in uploaded, and the approval stands.
• Until the first submit succeeds, submit explicitly. A PATCH before then only updates what we hold.

Decisions arrive on the endorsement

Each event carries the endorsement object GET /api/customers/{customer_id} embeds, plus object: "endorsement" and the customer_id. There are no verification.* webhooks.

The review's word stands in both directions. It can ask for more on an endorsement it already approved. The endorsement then moves from approved to issues and endorsement.request_for_information fires. Anything that needs the endorsement approved, such as creating a virtual account in its currency, is refused until it is approved again.

When we cannot reach the review, the endorsement shows issues with the single code unavailable. No webhook fires, the round is marked expired because it never reached the review, and we retry automatically with a new round. You need not act.

The one channel: requirement buckets

Every ask is a bare snake_case code in exactly one of five buckets.

Before the first submit, missing holds compliance_review: the submit itself is owed. A requested endorsement with everything held reads:

{
  "name": "endo_usd",
  "status": "incomplete",
  "requirements": {
    "complete": ["terms_of_service"],
    "uploaded": ["identity", "proof_of_address", "selfie"],
    "pending": [],
    "missing": ["compliance_review"],
    "issues": []
  }
}

missing lists everything the review needs that you have not supplied, with three rules for documents:

• A missing document is listed itself, such as identity, never the fields it would carry.
• A field a held document will supply is not listed while that document waits to be read. Whatever the reading cannot yield is listed after the submit, and the submit's 422 verification_incomplete names it. A document we cannot accept moves to issues.
• Optional documents are not owed. proof_of_tax_identification appears in a bucket only once you send one, except for a sole proprietorship, which owes it. Until then, the tax fields are asked as fields. Which documents are owed is in Documents we ask for.

For the endorsement's own statuses and transitions, see Statuses & Lifecycles.

Requirement codes

Buckets carry only the codes below: never prose, a field path, or a message from anyone else. A field code is satisfied by the customer field of the same name unless the table says otherwise.

Agreements and the review

Documents

Customer profile. In missing the field is absent. In issues it was supplied and refused. address is the residential address, or a business's registered one.

Business profile

Enhanced due diligence. The review asks for it per customer, based on its own risk assessment.

Asks the review could not pin to one field

Verdicts. Nothing you send fixes these.

Verification rounds

Each submission opens one round per endorsement it sends. GET /api/customers/{customer_id}/verifications lists them, newest first. Their statuses are in Statuses & Lifecycles.

{
  "id": "ver_033y1FhTOmoW9W2jAuSvQx",
  "object": "verification",
  "customer_id": "cus_033y1FhTOmoW9W2jAuSvQx",
  "endorsement": "endo_usd",
  "purpose": "full",
  "requested_info": null,
  "intake_method": "api",
  "status": "request_for_information",
  "url": null,
  "expires_at": null,
  "rejection_reasons": [{"requirement": "proof_of_address", "retryable": true}],
  "created_at": "2026-08-26T10:02:11+00:00"
}

What to ask your user for:

Whether an outcome is retryable is decided per decision, on each reason plus the round's status. Never assume it from the requirement alone.

Rounds carry no extracted identity data. The endorsement carries readiness, and your own records carry the dossier.

Fixing an ask

The fix is a PATCH, and the PATCH is the resubmission. There is no special endpoint and no second call.

curl -s -X PATCH $BASE/api/customers/cus_... \
  -H "Api-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"purpose": "proof_of_address", "file": "<base64>"}]}'

The endorsement in the response reads pending again, and a new round opens with purpose: "resubmission" and requested_info naming the asks it answers. If the endorsement still owes something, it stays in issues and the buckets say what.

What to render, per state