Skip to main content
Sessions are the unit of verification on Didit. When you start a verification, a session is created; when the verification finishes, the session carries the full decision payload. The same session API handles both kinds:
KindWhat it verifiesDecision payload includes
User Verification (KYC) sessionAn individual personID verification, liveness, face match, POA, NFC, database validation, phone, email, AML, questionnaires, IP analysis
Business Verification (KYB) sessionA company / legal entityCompany registry check, key people (officers/UBOs), document verifications, phone, email, AML, questionnaires, IP analysis

​
Kind is determined by the workflow

When you create a session, you pass a workflow_id. The workflow’s type determines whether the session is a User Verification or a Business Verification — callers do not choose separately. KYB workflows create Business Verification sessions; KYC workflows create User Verification sessions.

​
session_kind discriminator

Every session response — from create, retrieve, list, update-status, share, and import — includes a top-level field: 
{
  "session_id": "...",
  "session_kind": "user",
  ...
}
  • "user" — the session is a User Verification (KYC) session. The response contains user-specific feature arrays.
  • "business" — the session is a Business Verification (KYB) session. The response contains business-specific feature arrays.
Use this field to switch on shape on your side.
The enum values are the short identifiers "user" and "business" — we keep them short for API ergonomics. The full names User Verification (KYC) and Business Verification (KYB) are used throughout the documentation for clarity.

​
Feature arrays by kind

The feature arrays present in a decision depend on the kind. Fields absent from one kind simply do not appear in that response (no nulls, no placeholders):
Feature arrayUser Verification (KYC)Business Verification (KYB)
id_verifications✅—
liveness_checks✅—
face_matches✅—
nfc_verifications✅—
poa_verifications✅—
database_validations✅—
registry_checks—✅
document_verifications—✅
key_people_checks—✅
aml_screenings✅✅
phone_verifications✅✅
email_verifications✅✅
questionnaire_responses✅✅
ip_analyses✅✅
reviews✅✅
contact_details✅✅

​
Shared top-level fields

Every session (both kinds) carries these fields:
FieldDescription
session_idUUID of the session
session_kind"user" (User Verification / KYC) or "business" (Business Verification / KYB)
session_numberSequential number within the application
session_urlHosted verification URL
statusOverall session status — APPROVED, DECLINED, IN_REVIEW, IN_PROGRESS, etc.
workflow_idUUID of the workflow used
vendor_dataYour identifier for the entity. Learn more
metadataFree-form JSON you attached on creation
callbackOptional callback URL
featuresComma-separated feature list the workflow runs
expected_detailsOptional expected-data payload for cross-validation
created_at, expires_atTimestamps

​
Endpoints covered

The following endpoints all accept either kind. No separate /v3/business-session/* paths.
EndpointWorks for
POST /v3/session/Creates a User Verification or Business Verification session based on workflow type
GET /v3/session/{id}/decision/Retrieves either kind — dispatches on session_id
GET /v3/sessionsLists either kind. Use session_kind query parameter to filter
PATCH /v3/session/{id}/update-status/Updates either kind
DELETE /v3/session/{id}/delete/Deletes either kind
GET /v3/session/{id}/generate-pdfGenerates a PDF for either kind — routes to the User Verification or Business Verification template
POST /v3/session/{id}/share/Share token includes session_kind
POST /v3/session/import-shared/Imports either kind — preserves session_kind from the token

​
How lookups work

User Verification and Business Verification sessions live in different database tables. IDs use UUIDs so collisions are impossible. When you call an endpoint with a session_id, Didit:
  1. Looks up the id in the User Verification table first (covers most traffic).
  2. Falls back to the Business Verification table if not found.
  3. Returns 404 if neither table has a match.
You never need to tell the API which kind you’re looking for.

​
Statuses are identical

Status values are the same for both kinds: NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, ABANDONED, EXPIRED, RESUBMITTED, AWAITING_USER. See verification statuses for the full reference.

​
Webhooks

Webhook events already carry a session_kind field so your webhook handlers can dispatch per kind:
EventKindFires when
status.updatedBothA session’s status changed. Payload carries session_kind: "user" or "business".
data.updatedBothA session’s data changed (feature results, registry refresh, ongoing AML). Payload carries session_kind.
business.status.updated / business.data.updatedBusiness entityThe linked Business entity changed.
user.status.updated / user.data.updatedUser entityThe linked User entity changed.
See webhooks for signature verification and retry semantics, plus KYB webhooks for the Business Verification event catalog.

​
Next steps

Create session

Start a verification — User Verification or Business Verification.

Retrieve session

Fetch the decision. Works for both kinds.

List sessions

Filter by session_kind.

Update status

Approve, decline, review, resubmit.

Generate PDF

Per-kind PDF reports.

Share + import

Move sessions between apps.