User Lifecycle & Webhooks

The essentials

ℹ️

Three rules that cover almost everything

1. A user becomes ACTIVE only when both are true: KYC passed (kyc=true) and Terms & Conditions accepted (tnc=true).
2. When you receive a KYC_RFI webhook, present the rfiUrl from its payload to your customer. They complete it and the flow continues.
3. A KYC_REJECTED user is terminal — that orgUserId cannot be recovered. To let the customer retry, onboard them again with a new orgUserId.

Terms & Conditions acceptance is a separate API call (POST /api/v1/ol/user/tnc/update), not a webhook. KYC can pass while T&C is still pending; the user stays in PENDING until both are done.

---

Two statuses you track

A user carries two independent values. Read them together.

tnc (T&C accepted) is the third input that gates activation.

🚧

INACTIVE means two different things

Distinguish them by the kyc flag:

• userStatus=INACTIVE with kyc=false → Rejected. Terminal; onboard again with a new orgUserId.
• userStatus=INACTIVE with kyc=true → Frozen. Reversible; the user returns to ACTIVE on an UNFREEZE webhook.

---

Lifecycle

flowchart TD
    S[Client calls POST /user/create] --> C[CREATE · userStatus PENDING]
    C --> P[KYC_PENDING · verification started]
    P -->|more information needed| R[KYC_RFI · rfiUrl issued]
    R -->|customer resubmits| P
    P -->|verification passes| K[KYC_COMPLETED · kyc=true]
    R -->|verification passes| K
    P -->|cannot verify| X[KYC_REJECTED · terminal]
    R -->|cannot verify| X
    K -->|terms accepted| A[UPDATE · userStatus ACTIVE]
    A -->|compliance hold| F[userStatus INACTIVE · frozen]
    F -->|UNFREEZE| A
    A -->|periodic re-check| R2[KYC_RFI · post-activation]
    R2 -->|cleared| A
    A -->|offboard| D[DELETE · userStatus DELETED]

RFI is optional. A clean user goes straight from KYC_PENDING to KYC_COMPLETED — RFI only occurs when Fuze needs more information. In the API-driven onboarding method, you will additionally receive KYC_DOC_UPLOADED (once per document) and KYC_FORM_SUBMITTED between KYC_PENDING and KYC_COMPLETED; see Onboarding methods.

---

Onboarding methods

The webhooks you receive depend on how KYC is performed. The same lifecycle applies; only the document-level events differ, because a webhook is sent only for a step that actually occurs on your integration.

ℹ️

How this page is organised

The event payloads are identical across all methods — only which events fire, and in what order, changes. Each method section below gives just that method's sequences and the events it never receives; see Webhook events for the event summary and the Webhooks page for full payloads. Find your method, read that section.

Which webhooks each method sends

Fuze-Hosted

The customer completes verification on a Fuze-hosted page. You request a KYC link and present it; Fuze handles document capture internally. This is DomePe's V1 flow.

• You receive: CREATE, KYC_PENDING, KYC_RFI (only if needed), KYC_COMPLETED or KYC_REJECTED, UPDATE.
• You never receive: KYC_DOC_UPLOADED, KYC_FORM_SUBMITTED.

KYC Reliance

You have already verified the customer under your own approved process and assert this to Fuze via API. Fuze runs its own screening and completes onboarding. This is the most minimal flow.

• You receive: CREATE, KYC_COMPLETED or KYC_REJECTED, UPDATE; KYC_RFI only in the rare case Fuze's screening needs more. A brief KYC_PENDING may appear while Fuze screens.
• You never receive: KYC_DOC_UPLOADED, KYC_FORM_SUBMITTED.

---

Possible webhooks from each state

What you can receive next, given where the user is. A blank means that transition does not occur.

---

Post-activation sequences (all methods)

Once a user is ACTIVE, these apply regardless of onboarding method.

---

Handling edge cases

👍

Responding to an RFI

Present the rfiUrl to the customer. If Fuze needs something different afterwards, you will receive another KYC_RFI: a new request carries a new link; a resend of the same request carries the same link. There is no counter for you to maintain.

🚧

Rejection is terminal

KYC_REJECTED is final for that orgUserId. It may arrive after an RFI or directly — always handle it as terminal whenever it arrives, and do not assume an RFI will always precede it. To retry, onboard the customer again under a new orgUserId.

ℹ️

KYC passed but the user is not ACTIVE

This means T&C has not been accepted yet. Confirm your POST /api/v1/ol/user/tnc/update call succeeded. The user activates only when kyc=true and tnc=true.

ℹ️

Re-checks on active users (post-activation RFI)

An already-ACTIVE user can receive a KYC_RFI — for example a periodic sanctions re-check or an expired document. Surface the link as usual; the user may be paused until it clears.

Design your handler as a state machine, not a fixed sequence: act on the webhook you receive given the user's current state. Webhooks may arrive more than once or slightly out of order (see Webhooks → delivery & retries), so make your processing idempotent.

---

Webhook events

User-entity events and when they fire. Full payloads use the standard event + data envelope and are documented on the Webhooks reference page — they are identical across onboarding methods.

---

Related pages

• Webhooks — full payloads, setup, signature verification, delivery and retry policy.
• KYC / KYB — onboarding methods and document categories in detail.
• Users — the user object and management APIs.