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

# Entity Lifecycle

> States and transitions for Didit User and Business entities — creation, verification, ACTIVE/FLAGGED/BLOCKED transitions, and deletion. Pay-per-call.

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Created (API, console, or auto from session)
    ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern
    FLAGGED --> ACTIVE: Analyst clears / remediation completed
    ACTIVE --> BLOCKED: Session declined / manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## Statuses in detail

| Status    | Meaning                                     | Enforcement                                                                                                                    |
| --------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `ACTIVE`  | Default — entity is in good standing        | New sessions and transactions run through your configured workflows and rules                                                  |
| `FLAGGED` | Entity has a pending issue requiring review | New sessions still run but default to `IN_REVIEW`; transactions may auto-escalate depending on rules                           |
| `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` |

<Note>
  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.
</Note>

## Phases of the lifecycle

<Steps>
  <Step title="Creation" icon="plus">
    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.
  </Step>

  <Step title="Verification" icon="shield-check">
    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.

    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`).
  </Step>

  <Step title="Active usage" icon="chart-line">
    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
  </Step>

  <Step title="Status transitions" icon="arrows-rotate">
    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.
  </Step>

  <Step title="Deletion" icon="trash">
    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.

    Hard deletion happens only at the end of the retention window.
  </Step>
</Steps>

## Activity timestamps

Entities track activity to help you identify stale or active profiles:

| Timestamp          | Updated when                                                              |
| ------------------ | ------------------------------------------------------------------------- |
| `first_session_at` | The first session was created for this entity                             |
| `last_session_at`  | The most recent session was created or updated                            |
| `last_activity_at` | Any 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 phase              | Webhooks emitted                                                           |
| ---------------------------- | -------------------------------------------------------------------------- |
| Creation (auto from session) | `status.updated` (session), `user.data.updated` or `business.data.updated` |
| Verification                 | `status.updated` (session), `data.updated`, `business_session.*` for KYB   |
| Status change                | `user.status.updated` or `business.status.updated`                         |
| Transaction submitted        | `transaction.created`                                                      |
| Transaction status changed   | `transaction.status.updated`                                               |
| Activity logged              | `activity.created`                                                         |

See [entity webhooks](/entities/webhooks) for payload shapes and delivery semantics.

## Next steps

<CardGroup cols={3}>
  <Card title="Vendor data linking" icon="link" href="/entities/vendor-data-linking">
    How `vendor_data` ties sessions, transactions, and entities together.
  </Card>

  <Card title="User operations" icon="user-pen" href="/entities/users/operations">
    Create, update, change status, and delete User entities.
  </Card>

  <Card title="Business operations" icon="building-columns" href="/entities/businesses/operations">
    Create, update, change status, and delete Business entities.
  </Card>
</CardGroup>