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

kyc_statusWhat it meansNext move
NOT_STARTEDRecord created via API. Back office has not yet started KYC.Back office completes risk questions in-app, clicks Start Verification.
PENDINGKYC initiated, link generated, customer not yet started.Customer opens the verification link.
IN_PROGRESSCustomer is in the Sumsub flow.Sumsub returns a verdict.
VERIFIEDIdentity confirmed. Check aml.status for AML state.See AML statuses below.
FAILEDIdentity rejected.Manual review or re-ingest.
AWAITING_RESUBMISSIONCustomer must resubmit something (poor photo, expired ID, etc.).Customer resubmits, returns to IN_PROGRESS.
NOT_REQUIREDDesignated service not in scope for this customer.Nothing to do.

​
AML status

Once kyc_status = VERIFIED, the AML block tells you the screening outcome:
aml.statusMeaning
NOT_SCREENEDAML screening has not run.
IN_PROGRESSScreening is mid-flight.
CLEARNo matches. Customer is fully cleared.
NEEDS_REVIEWHits found; the firm’s compliance team is reviewing them.
RESOLVEDAll hits reviewed and a final decision recorded.

​
How your CRM should react

kyc_statusaml.statusWhat to surface in your CRM
VERIFIEDCLEARCleared. Safe to onboard.
VERIFIEDNEEDS_REVIEW”Identity OK — AML in review.” Don’t onboard yet.
VERIFIEDRESOLVED”Final decision recorded.” Check your firm’s process.
FAILED—“Rejected.” Don’t onboard.
AWAITING_RESUBMISSION—“Customer needs to resubmit ID.” Send a friendly nudge.

​
Why the API does not trigger KYC

Triggering KYC is the billable, irreversible moment in the flow: real-money credits are deducted and a Sumsub applicant is created. We intentionally keep this behind a human in your firm so that:
  • The risk questions (designated service, cash/crypto, new vs existing client) are completed by a human who can interpret them.
  • No automated retry loop can ever rack up KYC charges.
  • Your Compliance Officer always has a hand on the wheel.
The natural shape: your CRM pushes customers in, your firm decides when to verify, your CRM pulls status out.

​
Field reference

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