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

# Onboarding events

> customer.created and kyc.* webhooks: when a customer is created and as their verification progresses, the payload each carries, and example deliveries

Endl sends onboarding webhooks when you create or import a customer and as that
customer moves through identity verification (KYC for individuals, KYB for
businesses). Use them to keep your own records up to date without polling
[Get customer](https://docs.endl.io/api-reference/onboarding/get-customer.md).

| Event | When it fires | `data.status` |
| - | - | - |
| `customer.created` | A customer is created or imported | `INITIATED`, or the imported status |
| `kyc.submitted` | Verification has started and is being processed or reviewed | `PENDING` or `IN_REVIEW` |
| `kyc.action_required` | The customer needs to fix or resubmit something | `RESUBMISSION_REQUIRED` |
| `kyc.on_hold` | Verification is paused for manual review | `ON_HOLD` |
| `kyc.completed` | The customer is approved | `COMPLETED` |
| `kyc.rejected` | The customer is rejected (final) | `REJECTED` |

All six events:

* relate to a customer, so `data.id` and `data.customerId` both hold the customer's `cus_…` id
* use the standard envelope, signature and retry rules from the [Webhooks guide](https://docs.endl.io/guides/webhooks.md)
* apply to both `INDIVIDUAL` and `BUSINESS` customers; `data.userType` tells you which

**Subscribing:** use `"eventFilter": ["customer.*", "kyc.*"]` to receive all of them,
or list individual event types.

## Payload fields

| Field | Type | Sent on | Description |
| - | - | - | - |
| `id` | string | all | The customer's id (`cus_…`). |
| `customerId` | string | all | The customer's id (`cus_…`). Same value as `id`. |
| `userType` | string | all | `INDIVIDUAL` or `BUSINESS`. |
| `status` | string | all | The customer's verification status at the time of the event. See [Status values](#status-values). |
| `previousStatus` | string | `kyc.*` only, when available | The status before this change. Left out when the earlier status was internal (for example, right after the customer was created). |
| `reason` | string | `kyc.action_required`, `kyc.rejected` | A readable explanation of what went wrong or what the customer needs to fix. Left out when no reason is available. |
| `rejectionCodes` | array of strings | `kyc.action_required`, `kyc.rejected` | Machine-readable reasons, such as `UNSATISFACTORY_PHOTOS` or `DOCUMENT_PAGE_MISSING`. Left out when there are none. See [rejectionCodes](#rejectioncodes). |

Standard rendering rules apply: every leaf value is a string, null fields are left
out, keys are sorted, and new fields can appear without a version change. Read
optional fields defensively.

## Status values

| `status` | Meaning | Comes with |
| - | - | - |
| `INITIATED` | The customer has been created and verification hasn't started yet. | `customer.created` |
| `PENDING` | Documents or data have been submitted and verification is being processed. | `kyc.submitted` (also `customer.created` on import) |
| `IN_REVIEW` | Verification is under review. | `kyc.submitted` |
| `RESUBMISSION_REQUIRED` | The customer must correct or re-upload something. This status isn't final. | `kyc.action_required` |
| `ON_HOLD` | Verification is paused for manual or compliance review. This status isn't final. | `kyc.on_hold` |
| `COMPLETED` | The customer is approved. This status is final. | `kyc.completed` (also `customer.created` on import) |
| `REJECTED` | The customer is rejected. This status is final. | `kyc.rejected` (also `customer.created` on import) |

## Typical lifecycle

```text theme={null}
customer.created             (INITIATED)
        │
        │  customer completes the KYC link / documents are uploaded
        ▼
kyc.submitted                (PENDING → IN_REVIEW)
        │
        ├──► kyc.completed           (approved, final)
        ├──► kyc.rejected            (rejected, final)
        ├──► kyc.on_hold             ──► later: kyc.submitted / kyc.completed / kyc.rejected
        └──► kyc.action_required     ──► customer resubmits ──► kyc.submitted ──► …
```

Things to know:

* **One event per status change.** An event fires only when the status actually
  changes. A repeat of the same status sends nothing.
* **`kyc.submitted` can arrive more than once**, for example once for `PENDING` and
  again for `IN_REVIEW`, and again after each resubmission.
* **`kyc.action_required` can repeat** if the customer resubmits and still needs
  another correction.
* **Imported customers get a `customer.created` event that already carries their
  imported status** (`COMPLETED`, `REJECTED` or `PENDING`). No separate `kyc.*`
  event follows for that starting status.
* **Order isn't guaranteed across retries.** Use `eventCreatedAt` and `status` to
  make sure you never overwrite a newer state with an older one. If you're unsure,
  call Get customer: the API is always the source of truth.

## Events in detail

### customer.created

**When:** a customer is created ([Create customer](https://docs.endl.io/api-reference/onboarding/create-customer.md))
or imported, for both individuals and businesses. This is the first event you get
for a new `cus_` id.

**Payload:** `status` is `INITIATED` for a newly created customer, or, for an
imported customer, the imported verification outcome: `COMPLETED`, `REJECTED` or
`PENDING`. Plus `userType`.

**What to do:** store the `cus_` id and start tracking the customer. If `status` is
`INITIATED`, send the customer the [KYC link](https://docs.endl.io/api-reference/onboarding/generate-kyc-link.md).

```json theme={null}
{
  "eventId": "7b1f2e90-4c3a-5d21-9f7e-6a1c0b5d2e34",
  "eventType": "customer.created",
  "eventCategory": "customer",
  "eventCreatedAt": "2026-10-21T09:15:04.500Z",
  "version": "2026-09.1",
  "data": {
    "id": "cus_PWEhqXkPKpWXiFd96jGq",
    "customerId": "cus_PWEhqXkPKpWXiFd96jGq",
    "status": "INITIATED",
    "userType": "INDIVIDUAL"
  }
}
```

### kyc.submitted

**When:** the customer's verification moves to `PENDING` (submitted and being
processed) or `IN_REVIEW` (under review).

**Payload:** `status` (`PENDING` or `IN_REVIEW`), `previousStatus` when available
(for example `RESUBMISSION_REQUIRED` after a resubmission), and `userType`.

**What to do:** show the customer as "verification in progress". You don't need to
do anything else; wait for a final outcome.

```json theme={null}
{
  "eventId": "c2a7d1e4-8b3f-3a19-a6c2-1f0e9d8b7a65",
  "eventType": "kyc.submitted",
  "eventCategory": "kyc",
  "eventCreatedAt": "2026-10-21T09:20:11.250Z",
  "version": "2026-09.1",
  "data": {
    "id": "cus_PWEhqXkPKpWXiFd96jGq",
    "customerId": "cus_PWEhqXkPKpWXiFd96jGq",
    "previousStatus": "PENDING",
    "status": "IN_REVIEW",
    "userType": "INDIVIDUAL"
  }
}
```

### kyc.action\_required

**When:** verification can't be completed until the customer fixes something, such
as a blurry photo, a missing page or an expired document. The status is
`RESUBMISSION_REQUIRED`. This status isn't final.

**Payload:** `status` (`RESUBMISSION_REQUIRED`), `reason` (what needs fixing,
written so you can show it to the customer), `rejectionCodes` (machine-readable
codes), `previousStatus` and `userType`.

**What to do:**

1. Tell the customer what to fix, using `reason`.
2. Have them resubmit, either through the KYC link or by
   [uploading documents](https://docs.endl.io/api-reference/onboarding/upload-document.md) again.
3. Expect `kyc.submitted` next.

```json theme={null}
{
  "eventId": "e5f6a7b8-1c2d-3e4f-9a0b-6c7d8e9f0a1b",
  "eventType": "kyc.action_required",
  "eventCategory": "kyc",
  "eventCreatedAt": "2026-10-21T10:02:40.000Z",
  "version": "2026-09.1",
  "data": {
    "id": "cus_PWEhqXkPKpWXiFd96jGq",
    "customerId": "cus_PWEhqXkPKpWXiFd96jGq",
    "previousStatus": "IN_REVIEW",
    "reason": "The photo of the document is blurry. Please upload a clear image.",
    "rejectionCodes": ["UNSATISFACTORY_PHOTOS"],
    "status": "RESUBMISSION_REQUIRED",
    "userType": "INDIVIDUAL"
  }
}
```

### kyc.on\_hold

**When:** verification is paused for manual or compliance review. The status is
`ON_HOLD`. This status isn't final.

**Payload:** `status` (`ON_HOLD`), `previousStatus` and `userType`. No `reason` is sent.

**What to do:** show the customer as "under review". The customer doesn't need to do
anything. Wait for the next event: usually `kyc.completed` or `kyc.rejected`, and
sometimes `kyc.action_required`.

```json theme={null}
{
  "eventId": "0a1b2c3d-4e5f-3a6b-8c7d-9e0f1a2b3c4d",
  "eventType": "kyc.on_hold",
  "eventCategory": "kyc",
  "eventCreatedAt": "2026-10-21T10:30:00.000Z",
  "version": "2026-09.1",
  "data": {
    "id": "cus_Q8mZr2LkTt4Hv9WbXyNc",
    "customerId": "cus_Q8mZr2LkTt4Hv9WbXyNc",
    "previousStatus": "IN_REVIEW",
    "status": "ON_HOLD",
    "userType": "BUSINESS"
  }
}
```

### kyc.completed

**When:** the customer passes verification. The status is `COMPLETED`, and it's final.

**Payload:** `status` (`COMPLETED`), `previousStatus` and `userType`. No `reason` is sent.

**What to do:** mark the customer as verified. They can now use the products that
require KYC or KYB, such as accounts, payouts and cards.

```json theme={null}
{
  "eventId": "9d8c7b6a-5f4e-3d2c-8b1a-0f9e8d7c6b5a",
  "eventType": "kyc.completed",
  "eventCategory": "kyc",
  "eventCreatedAt": "2026-10-21T11:45:09.750Z",
  "version": "2026-09.1",
  "data": {
    "id": "cus_PWEhqXkPKpWXiFd96jGq",
    "customerId": "cus_PWEhqXkPKpWXiFd96jGq",
    "previousStatus": "IN_REVIEW",
    "status": "COMPLETED",
    "userType": "INDIVIDUAL"
  }
}
```

### kyc.rejected

**When:** the customer fails verification. The status is `REJECTED`, and it's final:
the customer can't retry.

**Payload:** `status` (`REJECTED`), `reason` and `rejectionCodes` when available,
`previousStatus` and `userType`.

**What to do:** mark the customer as rejected and don't offer services that need KYC.
Some rejection reasons, such as compliance or screening matches, are deliberately
not shared. In that case `reason` or `rejectionCodes` may be missing or only partly
filled in.

```json theme={null}
{
  "eventId": "3c4d5e6f-7a8b-3c9d-8e0f-1a2b3c4d5e6f",
  "eventType": "kyc.rejected",
  "eventCategory": "kyc",
  "eventCreatedAt": "2026-10-21T12:05:33.100Z",
  "version": "2026-09.1",
  "data": {
    "id": "cus_PWEhqXkPKpWXiFd96jGq",
    "customerId": "cus_PWEhqXkPKpWXiFd96jGq",
    "previousStatus": "IN_REVIEW",
    "reason": "The identity document could not be verified.",
    "rejectionCodes": ["ID_INVALID"],
    "status": "REJECTED",
    "userType": "INDIVIDUAL"
  }
}
```

## rejectionCodes

* These codes come from the verification provider and describe what went wrong, for
  example `UNSATISFACTORY_PHOTOS`, `DOCUMENT_PAGE_MISSING`, `ID_INVALID` or
  `SELFIE_MISMATCH`.
* **Treat the list as open-ended.** New codes can appear, so don't reject a delivery
  because you don't recognise a code.
* **Compliance-sensitive codes are never sent**, even when they caused the outcome.
  That includes sanctions, criminal-record, blacklist and fraud-pattern matches. A
  rejection can therefore arrive with an empty or partial list.
* For anything you show the customer, use `reason`. Use `rejectionCodes` for routing
  and analytics.

## Best practices

* **Verify the signature, then deduplicate on `eventId`, then act.** Delivery is at
  least once, so the same event can arrive twice.
* **Don't move a customer backwards.** Ignore an event whose `eventCreatedAt` is
  older than the latest one you've processed for that customer.
* **Treat `COMPLETED` and `REJECTED` as final.** Only `RESUBMISSION_REQUIRED` and
  `ON_HOLD` can change to another status.
* **Use the API as the source of truth.** Webhooks tell you that something changed.
  If an event is missing or out of order, call
  [Get customer](https://docs.endl.io/api-reference/onboarding/get-customer.md).
* **Subscribe with globs (`kyc.*`, `customer.*`)** so you automatically receive new
  onboarding events Endl adds later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.