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

StatusMeaningEnforcement
ACTIVEDefault — entity is in good standingNew sessions and transactions run through your configured workflows and rules
FLAGGEDEntity has a pending issue requiring reviewNew sessions still run but default to IN_REVIEW; transactions may auto-escalate depending on rules
BLOCKEDEntity is blocked from your platformNew sessions are auto-declined; new transactions are auto-declined; no new session links can be created for this vendor_data
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:
TimestampUpdated when
first_session_atThe first session was created for this entity
last_session_atThe most recent session was created or updated
last_activity_atAny change happened — session, transaction, status change, profile update
Use these timestamps to filter dormant entities, schedule re-verifications, or trigger ongoing monitoring.

​
Events emitted during the lifecycle

Lifecycle phaseWebhooks emitted
Creation (auto from session)status.updated (session), user.data.updated or business.data.updated
Verificationstatus.updated (session), data.updated, business_session.* for KYB
Status changeuser.status.updated or business.status.updated
Transaction submittedtransaction.created
Transaction status changedtransaction.status.updated
Activity loggedactivity.created
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.