"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { p: "p", ..._provideComponents(), ...props.components }, {Heading, Mermaid} = _components; if (!Heading) _missingMdxReference("Heading", true); if (!Mermaid) _missingMdxReference("Mermaid", true); return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "Every User and Business entity in Didit moves through a predictable lifecycle. Understanding this lifecycle is the key to designing your onboarding, ongoing monitoring, and remediation flows." }), "\n", _jsx(Heading, { level: "2", id: "lifecycle-diagram", children: "Lifecycle diagram" }), "\n", _jsx(Mermaid, { chart: "stateDiagram-v2\n [*] --> ACTIVE: Created (API, console, or auto from session)\n ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern\n FLAGGED --> ACTIVE: Analyst clears / remediation completed\n ACTIVE --> BLOCKED: Session declined / manual block / blocklist match\n FLAGGED --> BLOCKED: Investigation concludes blocked\n BLOCKED --> ACTIVE: Manual unblock (analyst only)\n \n\n## Statuses in detail\n\n| Status | Meaning | Enforcement |\n|--------|---------|-------------|\n| `ACTIVE` | Default — entity is in good standing | New sessions and transactions run through your configured workflows and rules |\n| `FLAGGED` | Entity has a pending issue requiring review | New sessions still run but default to `IN_REVIEW`; transactions may auto-escalate depending on rules |\n| `BLOCKED` | Entity is blocked from your platform | New sessions are auto-declined; new transactions are auto-declined; no new session links can be created for this `vendor_data` |\n\n\nChanging status via `PATCH /v3/users/{vendor_data}/update-status/` or `PATCH /v3/businesses/{vendor_data}/update-status/` emits a webhook (`user.status.updated` / `business.status.updated`) so downstream systems can react in real time.\n\n\n## Phases of the lifecycle\n\n\n \n An entity is created in one of three ways:\n\n - **Auto-created** when you start a session with a new `vendor_data`. The entity is created in `ACTIVE` status.\n - **Pre-created via API** using `POST /v3/users/create/` or `POST /v3/businesses/create/`. Status defaults to `ACTIVE`.\n - **Created in the console** by a compliance operator — status starts at `ACTIVE` unless the operator specifies otherwise.\n\n Every entity gets a Didit-generated `uuid` and a customer-owned `vendor_data` identifier.\n \n\n \n Sessions are attached to the entity via `vendor_data`. Each session runs through your configured [workflow](/console/workflows) — ID verification, liveness, face match, AML, documents, registry lookup for KYB, and so on.\n\n Completed sessions update the entity's aggregate counters:\n\n - `session_count`, `approved_count`, `declined_count`, `in_review_count`\n - `features` map — the latest status of each feature across all sessions (e.g. `{ \"id_verification\": \"APPROVED\", \"aml\": \"IN_REVIEW\" }`)\n - Profile fields propagate from the latest approved session (e.g. `full_name`, `date_of_birth`, `portrait_image`).\n \n\n \n Once an entity has one or more approved sessions, you can:\n\n - **Submit transactions** referencing the entity via `vendor_data` in the transaction payload\n - **Run ongoing AML monitoring** — periodic rescans of sanctions / PEP / adverse media lists\n - **Re-verify on a schedule** — create new sessions for the same `vendor_data` at regular intervals\n - **Aggregate risk signals** across sessions and transactions\n \n\n \n Entity status changes happen automatically or manually.\n\n **Automatic transitions**\n - `ACTIVE → BLOCKED` when a session is `DECLINED` and your workflow is configured to auto-block.\n - `ACTIVE → FLAGGED` when a transaction crosses the review threshold or a rule adds the entity to a watchlist.\n - `ACTIVE → BLOCKED` when a face biometric matches a blocklist entry.\n\n **Manual transitions** happen when an analyst changes status from the console or when you call the `update-status` endpoint.\n\n Every transition emits a `user.status.updated` or `business.status.updated` webhook.\n \n\n \n Entities are deleted via `POST /v3/users/delete/` or `POST /v3/businesses/delete/` (batch). History (sessions, transactions, audit trail) is retained for your configured [data retention](/console/data-retention) period.\n\n Hard deletion happens only at the end of the retention window.\n \n\n\n## Activity timestamps\n\nEntities track activity to help you identify stale or active profiles:\n\n| Timestamp | Updated when |\n|-----------|--------------|\n| `first_session_at` | The first session was created for this entity |\n| `last_session_at` | The most recent session was created or updated |\n| `last_activity_at` | Any change happened — session, transaction, status change, profile update |\n\nUse these timestamps to filter dormant entities, schedule re-verifications, or trigger ongoing monitoring.\n\n## Events emitted during the lifecycle\n\n| Lifecycle phase | Webhooks emitted |\n|-----------------|------------------|\n| Creation (auto from session) | `status.updated` (session), `user.data.updated` or `business.data.updated` |\n| Verification | `status.updated` (session), `data.updated`, `business_session.*` for KYB |\n| Status change | `user.status.updated` or `business.status.updated` |\n| Transaction submitted | `transaction.created` |\n| Transaction status changed | `transaction.status.updated` |\n| Activity logged | `activity.created` |\n\nSee [entity webhooks](/entities/webhooks) for payload shapes and delivery semantics.\n\n## Next steps\n\n\n \n How `vendor_data` ties sessions, transactions, and entities together.\n \n \n Create, update, change status, and delete User entities.\n \n \n Create, update, change status, and delete Business entities.\n \n" })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

Documentation Index

​Lifecycle diagram

Lifecycle diagram