Skip to main content
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.

​
Lifecycle diagram

​
Statuses in detail

Changing 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.

​
Phases of the lifecycle

Creation

An entity is created in one of three ways:
  • Auto-created when you start a session with a new vendor_data. The entity is created in ACTIVE status.
  • Pre-created via API using POST /v3/users/create/ or POST /v3/businesses/create/. Status defaults to ACTIVE.
  • Created in the console by a compliance operator — status starts at ACTIVE unless the operator specifies otherwise.
Every entity gets a Didit-generated uuid and a customer-owned vendor_data identifier.

Verification

Sessions are attached to the entity via vendor_data. Each session runs through your configured workflow — ID verification, liveness, face match, AML, documents, registry lookup for KYB, and so on.Completed sessions update the entity’s aggregate counters:
  • session_count, approved_count, declined_count, in_review_count
  • features map — the latest status of each feature across all sessions (e.g. { "id_verification": "APPROVED", "aml": "IN_REVIEW" })
  • Profile fields propagate from the latest approved session (e.g. full_name, date_of_birth, portrait_image).

Active usage

Once an entity has one or more approved sessions, you can:
  • Submit transactions referencing the entity via vendor_data in the transaction payload
  • Run ongoing AML monitoring — periodic rescans of sanctions / PEP / adverse media lists
  • Re-verify on a schedule — create new sessions for the same vendor_data at regular intervals
  • Aggregate risk signals across sessions and transactions

Status transitions

Entity status changes happen automatically or manually.Automatic transitions
  • ACTIVE → BLOCKED when a session is DECLINED and your workflow is configured to auto-block.
  • ACTIVE → FLAGGED when a transaction crosses the review threshold or a rule adds the entity to a watchlist.
  • ACTIVE → BLOCKED when a face biometric matches a blocklist entry.
Manual transitions happen when an analyst changes status from the console or when you call the update-status endpoint.Every transition emits a user.status.updated or business.status.updated webhook.

Deletion

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 period.Hard deletion happens only at the end of the retention window.

​
Activity timestamps

Entities track activity to help you identify stale or active profiles: Use these timestamps to filter dormant entities, schedule re-verifications, or trigger ongoing monitoring.

​
Events emitted during the lifecycle

See entity webhooks for payload shapes and delivery semantics.

​
Next steps

Vendor data linking

How vendor_data ties sessions, transactions, and entities together.

User operations

Create, update, change status, and delete User entities.

Business operations

Create, update, change status, and delete Business entities.