> ## 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.
# Entities Overview
> Users and Businesses are Didit's two first-class entities. Each one aggregates KYC sessions, transactions, documents, biometrics, and risk into one profile.
Didit organizes everything that happens in your application around two first-class entity types:
| Entity | Represents | Linked to |
| ------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **User** | An individual person | User Verification (KYC) sessions, face biometrics, transactions (as applicant/counterparty), blocklists |
| **Business** | A legal entity (company, LLC, sole proprietorship, fund) | Business Verification (KYB) sessions, officers, UBOs, transactions (as applicant/counterparty), blocklists |
Every verification session, every transaction, and every blocklist entry can be bound to an entity. Once bound, the entity becomes a durable profile that aggregates history, risk signals, and compliance state across time.
## Entity vs session
An **entity** and a **session** are different things.
| Concept | Scope | Lifespan | Example |
| ----------- | ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Session** | One verification event | Single flow (minutes to days while in review) | A single KYC attempt |
| **Entity** | A durable profile | Lives as long as the user/business exists on your platform | The customer "Jane Doe" with 3 User Verification (KYC) sessions over 2 years |
A single entity can have many sessions — re-verifications, resubmissions, add-on checks, periodic ongoing monitoring. The entity aggregates the results.
## Auto-creation vs manual pre-creation
Entities are created in one of three ways:
When you create a session with a `vendor_data` identifier and no matching entity exists, Didit creates the entity automatically. This is the most common path.
```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "workflow_id": "wf_kyc_standard", "vendor_data": "user-42" }'
```
A User entity for `user-42` is created the moment the session starts.
Create the entity first, then start sessions against it. Useful when you want to seed risk signals (status, tags, custom metadata) before the first verification.
```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "vendor_data": "user-42", "display_name": "Jane Doe" }'
```
Your compliance team can create users or businesses directly from the Business Console — useful for manual onboarding, imports, or remediation workflows.
## How entities link everything
The `vendor_data` field is the linking key. When you pass `vendor_data` on any session or transaction, Didit routes it to the matching entity.
```mermaid theme={null}
flowchart LR
VD["vendor_data:
user-42"] --> U[User entity]
S1[User Verification (KYC) session #1] --> VD
S2[User Verification (KYC) session #2] --> VD
T1[Transaction #1] --> VD
T2[Transaction #2] --> VD
F[Face biometric] --> VD
D[Documents] --> VD
BL[Blocklist entry] --> VD
```
Learn more in the [`vendor_data` linking guide](/entities/vendor-data-linking).
## What you can do with an entity
For each User or Business entity, you can:
| Operation | Purpose |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Create / update** | Set or change the entity's profile data (name, country, custom metadata) |
| **Change status** | Mark as `ACTIVE`, `FLAGGED`, or `BLOCKED` — enforcement propagates to future sessions and transactions |
| **Attach biometrics** | Upload a face reference for 1:N search, duplicate detection, or blocklisting |
| **Review KYC/KYB history** | Retrieve every session tied to the entity, with per-feature results |
| **Review transaction history** | Retrieve every transaction where the entity is the applicant or counterparty |
| **Add to a blocklist** | Block future sessions or transactions involving this entity |
| **Import / export** | Bulk upload entities from CSV or export for external compliance tooling |
| **Delete** | Delete the entity (history is preserved for audit) |
Detailed walkthroughs live under [Users](/entities/users/overview) and [Businesses](/entities/businesses/overview).
## User ↔ Business relationships
A single User can be linked to one or many Businesses. This happens naturally during KYB:
* A User might be a **director** of one Business and a **UBO** of another.
* A User's User Verification (KYC) session can be linked to a Business's Business Verification (KYB) session via the [Key People](/business-verification/key-people) flow.
Didit preserves these relationships — when you inspect a Business entity, you can see every linked User, and when you inspect a User entity, you can see every Business they are associated with.
## Lifecycle and statuses
Every entity has a status that governs whether Didit enforces blocks on new activity:
| Status | Effect |
| --------- | ---------------------------------------------------------------------------------------- |
| `ACTIVE` | Normal — sessions and transactions proceed as configured by workflows and rules |
| `FLAGGED` | Sessions and transactions are allowed, but automatically routed to manual review |
| `BLOCKED` | Sessions and transactions are automatically declined, and no new sessions can be created |
See the full [entity lifecycle](/entities/lifecycle) for transitions and webhook events.
## Next steps
States, transitions, and lifecycle events for every entity.
How `vendor_data` binds sessions, transactions, and entities.
Deep dive on User entities, operations, and console workflows.
Deep dive on Business entities, operations, and console workflows.
Real-time events for every entity change.
How blocklist entries interact with User and Business entities.