Customer lifecycle - Instant Compliance API

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_status`	What it means	Next move
`NOT_STARTED`	Record created via API. Back office has not yet started KYC.	Back office completes risk questions in-app, clicks Start Verification.
`PENDING`	KYC initiated, link generated, customer not yet started.	Customer opens the verification link.
`IN_PROGRESS`	Customer is in the Sumsub flow.	Sumsub returns a verdict.
`VERIFIED`	Identity confirmed. Check `aml.status` for AML state.	See AML statuses below.
`FAILED`	Identity rejected.	Manual review or re-ingest.
`AWAITING_RESUBMISSION`	Customer must resubmit something (poor photo, expired ID, etc.).	Customer resubmits, returns to `IN_PROGRESS`.
`NOT_REQUIRED`	Designated 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.status`	Meaning
`NOT_SCREENED`	AML screening has not run.
`IN_PROGRESS`	Screening is mid-flight.
`CLEAR`	No matches. Customer is fully cleared.
`NEEDS_REVIEW`	Hits found; the firm’s compliance team is reviewing them.
`RESOLVED`	All hits reviewed and a final decision recorded.

How your CRM should react

`kyc_status`	`aml.status`	What to surface in your CRM
`VERIFIED`	`CLEAR`	Cleared. Safe to onboard.
`VERIFIED`	`NEEDS_REVIEW`	”Identity OK — AML in review.” Don’t onboard yet.
`VERIFIED`	`RESOLVED`	”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.