Skip to main content
Didit organizes everything that happens in your application around two first-class entity types:
EntityRepresentsLinked to
UserAn individual personUser Verification (KYC) sessions, face biometrics, transactions (as applicant/counterparty), blocklists
BusinessA 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.
ConceptScopeLifespanExample
SessionOne verification eventSingle flow (minutes to days while in review)A single KYC attempt
EntityA durable profileLives as long as the user/business exists on your platformThe 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:
1

Auto-created from a session

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

Pre-created via the Management API

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.
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" }'
3

Created in the console

Your compliance team can create users or businesses directly from the Business Console — useful for manual onboarding, imports, or remediation workflows.
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. Learn more in the vendor_data linking guide.

​
What you can do with an entity

For each User or Business entity, you can:
OperationPurpose
Create / updateSet or change the entity’s profile data (name, country, custom metadata)
Change statusMark as ACTIVE, FLAGGED, or BLOCKED — enforcement propagates to future sessions and transactions
Attach biometricsUpload a face reference for 1:N search, duplicate detection, or blocklisting
Review KYC/KYB historyRetrieve every session tied to the entity, with per-feature results
Review transaction historyRetrieve every transaction where the entity is the applicant or counterparty
Add to a blocklistBlock future sessions or transactions involving this entity
Import / exportBulk upload entities from CSV or export for external compliance tooling
DeleteDelete the entity (history is preserved for audit)
Detailed walkthroughs live under Users and Businesses.

​
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 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:
StatusEffect
ACTIVENormal — sessions and transactions proceed as configured by workflows and rules
FLAGGEDSessions and transactions are allowed, but automatically routed to manual review
BLOCKEDSessions and transactions are automatically declined, and no new sessions can be created
See the full entity lifecycle for transitions and webhook events.

​
Next steps

Lifecycle

States, transitions, and lifecycle events for every entity.

Vendor data linking

How vendor_data binds sessions, transactions, and entities.

Users

Deep dive on User entities, operations, and console workflows.

Businesses

Deep dive on Business entities, operations, and console workflows.

Entity webhooks

Real-time events for every entity change.

Blocklist

How blocklist entries interact with User and Business entities.