> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantcompliance.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer lifecycle

> How a customer record moves from API ingest through KYC and AML.

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

```mermaid theme={null}
flowchart LR
  A[API POST /v1/customers] --> B(NOT_STARTED)
  B -->|back office triggers KYC| C(PENDING)
  C --> D(IN_PROGRESS)
  D -->|success| E(VERIFIED)
  D -->|reject| F(FAILED)
  D -->|needs resubmission| G(AWAITING_RESUBMISSION)
  G --> D
```

| `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](/api-reference/customers/get).