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

# Customer

> Webhook payloads for customer verification events

All customer webhooks are sent to your `collection_url`.

## Parameter overview

| Parameter        | Description                                                            |
| :--------------- | :--------------------------------------------------------------------- |
| `message`        | Human-readable description of the event.                               |
| `event_type`     | Event type identifier (e.g. `customer.status_changed`).                |
| `customer_id`    | Unique ID of the customer.                                             |
| `customer_email` | The customer's email address.                                          |
| `old_status`     | The customer's previous verification status.                           |
| `new_status`     | The customer's new verification status.                                |
| `comment`        | Optional comment explaining the status change (e.g. rejection reason). |
| `updated_at`     | ISO 8601 timestamp of when the status changed.                         |
| `event_id`       | Unique identifier for this webhook event.                              |
| `type`           | Always `customer` for customer events.                                 |

## The event

Customer-level transitions all fire a **single** event on the wire: `event_type = customer.status_changed`. The `old_status` and `new_status` fields tell you which way the customer just moved — for example `PENDING → VERIFIED`, `PROCESSING → REJECTED`, or `REJECTED → PROCESSING` (after a re-submission).

You will commonly hear about these as "the verified webhook" or "the rejected webhook" — that's shorthand for the same `customer.status_changed` event with `new_status=VERIFIED` or `new_status=REJECTED`. There are no separate `event_type` values for them on the wire.

### When the event fires

* **Verification approved** — `new_status=VERIFIED`. The customer can now be used for Virtual Bank Account creation, payouts, and any other operation that requires a verified customer.
* **Verification rejected** — `new_status=REJECTED`. Check the `comment` field for the customer-level reason. For business customers, also fetch `GET /api/external/customer/{id}` to read per-owner and per-document `admin_comments` arrays — the actionable per-record feedback lives there.
* **Submitted for review (business customers)** — `new_status=PROCESSING`, fired right after `POST /api/external/customer/{id}/submit`. Indicates the customer is now locked and under compliance review.
* **Reverted by admin** — `new_status=PENDING` after a previously-VERIFIED or REJECTED customer is moved back to PENDING by our operations team. Rare.

<Warning>
  **Verification is not instant.** After documents are uploaded (individual) or `/submit` is called (business), the customer enters a review process. You will not receive this webhook immediately — it arrives once the review is complete.

  For **individual customers**, the review finishes within a few minutes in most cases; up to 2 hours under additional screening. Do not raise support tickets within that window. Escalate only if pending for 5 hours or more.

  For **business customers**, KYB review typically takes **1–5 business days**. Do not raise tickets within that window. Escalate only if `PROCESSING` for more than 5 business days. See [Business customer KYB](/guides/kyb/overview).
</Warning>

## Example payload

```json theme={null}
{
  "message": "Customer verification status updated",
  "event_type": "customer.status_changed",
  "customer_id": "cust_abc123",
  "customer_email": "john@example.com",
  "old_status": "PENDING",
  "new_status": "VERIFIED",
  "comment": null,
  "updated_at": "2026-03-13T14:30:00.000Z",
  "event_id": "evt_def456",
  "type": "customer"
}
```

### Rejected example

```json theme={null}
{
  "message": "Customer verification status updated",
  "event_type": "customer.status_changed",
  "customer_id": "cust_abc123",
  "customer_email": "john@example.com",
  "old_status": "PENDING",
  "new_status": "REJECTED",
  "comment": "Identity document is expired.",
  "updated_at": "2026-03-13T14:30:00.000Z",
  "event_id": "evt_ghi789",
  "type": "customer"
}
```

## Possible statuses

| Status       | Description                                                                                                                                                                                                                                                                                                                                         |
| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING`    | Customer is editable; verification has not started yet. For individuals, this is the state right after creation. For businesses, this is the state until you call `POST /api/external/customer/{id}/submit`.                                                                                                                                        |
| `PROCESSING` | **Business customers only.** Customer is locked and under compliance review. Typically lasts 1–5 business days. Owner and KYB-document state changes during this window are not separately webhooked — wait for the customer-level transition.                                                                                                      |
| `VERIFIED`   | Customer KYC/KYB has been approved. The customer can now be used for payouts and (where supported) Virtual Bank Account creation.                                                                                                                                                                                                                   |
| `REJECTED`   | Customer was rejected. Check the `comment` field for the customer-level reason. For business customers, also fetch `GET /api/external/customer/{id}` to read per-owner and per-KYB-document `admin_comments` arrays — the per-record detail is where the actionable feedback lives. See [Handling KYB rejections](/guides/kyb/handling-rejections). |

<Note>
  **No per-owner or per-KYB-document webhooks.** For business customers, individual owner and document state changes during review do not emit webhooks. The customer-level `customer.status_changed` event is the only signal — when it fires with `new_status=VERIFIED` or `new_status=REJECTED`, fetch the customer to read the per-record state.
</Note>

## Verification timing

* **Individual customers**: typically a few minutes; up to 2 hours under additional screening. Do not escalate before 2 hours; contact operations only if pending for 5 hours or more.
* **Business customers**: typically 1–5 business days. Compliance reviews each owner and each KYB document individually. Do not escalate within the 5-business-day window. See [Business customer KYB](/guides/kyb/overview) for the full lifecycle.