Skip to main content
This is the state machine every customer ingested via the API runs through. Understanding it lets your CRM display the right status, send the right reminders, and only act on cleared customers.

​
Stages

​
AML status

Once kyc_status = VERIFIED, the AML block tells you the screening outcome:

​
How your CRM should react

​
Starting verification over the API

Triggering KYC/KYB is the billable moment in the flow: real-money credits are deducted (or the customer is billed) and the check is armed. Because of that, it is kept separate from ingest:
  • Ingesting never charges. Creating or updating a record via /customers or /entities only records the obligation — it never starts a check.
  • Starting is a distinct, scoped action. POST /customers/{id}/kyc and POST /entities/{id}/kyb run the same flows as the app and need the separate verification:write scope — a key can ingest without being able to spend, and only a key-holder with the in-app “Start checks” permission can mint a key that verifies.
  • One charge per record, fail-closed on empty credits. The same charge-before-arm and settlement rules as the app apply, so a retry loop can never double-charge, and an org with no credits gets a 402 with nothing armed.
The natural shape: your CRM pushes customers in, starts verification when your firm is ready (or a human does it in-app), and pulls status out.

​
Field reference

The full customer shape is documented in API reference → Customers → Get.