Skip to main content
POST
/
v3
/
session
cURL
curl -X POST 'https://verification.didit.me/v3/session/' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow_id": "11111111-2222-3333-4444-555555555555",
    "vendor_data": "user-123",
    "callback": "https://example.com/verification/callback",
    "callback_method": "both",
    "metadata": {"user_type": "premium", "account_id": "ABC123"},
    "language": "en",
    "contact_details": {
      "email": "john.doe@example.com",
      "send_notification_emails": true,
      "email_lang": "en",
      "phone": "+14155552671"
    },
    "expected_details": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-15",
      "id_country": "USA",
      "expected_document_types": ["P", "ID"]
    }
  }'
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_token": "abcdef1234567890",
  "url": "https://verify.didit.me/session/abcdef1234567890",
  "vendor_data": "user-123",
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "status": "Not Started",
  "callback": "https://example.com/verification/callback",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "workflow_version": 3
}

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.

​
Session kind

A single endpoint creates both User Verification and Business Verification sessions. The workflow’s type determines which kind:
  • Pass a KYC workflow workflow_id → a User Verification (KYC) session is created. Response session_kind: "user".
  • Pass a KYB workflow workflow_id → a Business Verification (KYB) session is created. Response session_kind: "business".
Configure workflows in the console at Workflows → Create workflow. A workflow is either KYC or KYB at creation time; you cannot switch types afterward.

​
Examples

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_KYC_WORKFLOW_ID",
    "vendor_data": "user-42",
    "callback": "https://yourapp.com/callback"
  }'
Response (201 Created):
{
  "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
  "session_kind": "user",
  "session_number": 1024,
  "session_token": "...",
  "url": "https://verify.didit.me/session/...",
  "status": "Not Started",
  "workflow_id": "YOUR_KYC_WORKFLOW_ID",
  "vendor_data": "user-42"
}

​
vendor_data binds the session to an entity

  • For KYC workflows: binds to a User entity. If the user doesn’t exist, it’s auto-created.
  • For KYB workflows: binds to a Business entity. Auto-created if new.
Learn more in vendor data linking. Create Session generates a verification URL and session token. It does not by itself prove that you showed the user the disclosures or obtained the consent required for your specific use case. If you start a Didit session from your own application, website, SDK wrapper, or white-label flow, you should handle the legal layer in your own UX before the user starts capture.
  1. Tell the user that your company is requesting the verification and that Didit is the verification provider / processor powering the flow.
  2. Link to your privacy notice and any controller-side legal terms that apply to the journey.
  3. Link to Didit’s Verification Privacy Notice and End User Terms for Identity Verification.
  4. If your workflow includes document capture, selfie capture, liveness, or biometrics, collect explicit affirmative consent wherever the applicable law or your legal position requires it.
  5. If you use a custom UI, custom domain, or API-only journey, render these disclosures in your own product before sending the user into the Didit flow.
  6. Keep your own record of notice / consent text, timestamp, and related metadata if your legal team requires an audit trail.
Legal requirements vary by jurisdiction. White-label branding does not remove Didit’s role in the verification flow. Review your implementation with counsel before launch if you operate in jurisdictions with biometric-specific rules.

Authorizations

​
x-api-key
string
header
required

Headers

​
Authorization
string
required

Authorization header in the format Bearer {client_access_token}. The access token is obtained from POST /auth/v2/token/ using your client credentials.

Example:

"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Content-Type
string
required

Must be set to application/json.

Example:

"application/json"

Body

application/json
​
workflow_id
string<uuid>
required

Stable identifier of the workflow that defines which verification steps the session will run. Workflows are created and managed in the Workflows page of the Console. The workflow_id also implicitly selects whether the session is KYC or KYB.

Example:

"11111111-2222-3333-4444-555555555555"

​
vendor_data
string

A unique identifier for the user being verified, such as a UUID, email, or internal user ID. This field is used for: (1) User grouping — sessions with the same vendor_data are linked to the same user profile in the Users tab. (2) Cross-session duplicate detection — when checking for duplicated faces, documents, phone numbers, emails, IP addresses, or device fingerprints, sessions with the same vendor_data are treated as the same user and excluded from matches. Without vendor_data, every session is treated as a unique user and all potential duplicates are surfaced. We strongly recommend always providing a vendor_data to reduce noise in duplicate detection.

Example:

"user-123"

​
callback
string

URL to redirect the user to after verification completes. Didit automatically appends verificationSessionId and status (Approved, Declined, In Review) as query parameters. Custom URL schemes (e.g. myapp://) are supported for mobile callbacks. If omitted, the workflow's default callback_url is used.

Example:

"https://example.com/verification/callback"

​
callback_method
enum<string>
default:initiator

Determines which device should handle the redirect to the provided callback URL. Use initiator to redirect only the device that started the flow, completer for the device that finishes it, or both to allow either device to trigger the callback. If you ever notice the callback not triggering reliably, we recommend setting this value to both.

Available options:
initiator,
completer,
both
Example:

"both"

​
metadata
object

Arbitrary JSON object stored with the session and echoed back in the response and webhooks. Not shown to the end user. Use it to pass your own correlation ids, A/B variants, or business context.

Example:
{
  "user_type": "premium",
  "account_id": "ABC123"
}
​
language
enum<string>

Language code (ISO 639-1) for the verification process interface. Controls the language displayed to the end user during verification. If not provided, the browser's language will be automatically detected and used. Check all the supported languages here.

Available options:
en,
ar,
bg,
bn,
bs,
ca,
cnr,
cs,
da,
de,
el,
es,
et,
fa,
fi,
fr,
he,
hi,
hr,
hu,
hy,
id,
it,
ja,
ka,
kk,
ko,
ky,
lt,
lv,
mk,
ms,
nl,
no,
pl,
pt-BR,
pt,
ro,
ru,
sk,
sl,
so,
sq,
sr,
sv,
th,
tr,
uk,
uz,
vi,
zh-CN,
zh-TW,
zh
Example:

"en"

​
contact_details
object

User contact information that can be used for notifications, prefilling verification forms, and phone verification. This includes email address, preferred language for communications, and phone number.

Example:
{
  "email": "john.doe@example.com",
  "send_notification_emails": true,
  "email_lang": "en",
  "phone": "+14155552671"
}
​
expected_details
object

Expected user details used to cross-validate against the data extracted from the user's ID document, Proof of Address, and other verification steps. Mismatches are surfaced as warnings on the decision; some fields (e.g. id_country, expected_document_types) also alter the user-facing flow.

Example:
{
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "nationality": "USA",
  "id_country": "USA",
  "expected_document_types": ["P", "ID"]
}
​
portrait_image
string<byte>

Base64-encoded portrait image of the end user's face (max 2MB; JPEG/PNG/WebP). Required when the workflow is a Biometric Authentication workflow with Face Match enabled, or any graph workflow where Face Match runs before ID Verification (OCR). Used as the reference image to match against the liveness capture. Disallowed for other workflow types.

Example:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="

Response

Session created (or returned, if an unfinished session with the same workflow_id + vendor_data already exists for the application). The response is the serialized session, including the hosted verification url to redirect the user to.

​
session_id
string<uuid>
required

Unique identifier of the verification session. Use this id when calling GET /v3/session/{sessionId}/decision/.

Example:

"11111111-2222-3333-4444-555555555555"

​
session_number
integer
required

Sequential, human-friendly number assigned to the session inside your application. Useful for support and dashboards.

Example:

43762

​
session_token
string
required

Short-lived token that authorizes the end user to access the hosted verification flow at url. Treat it as a secret.

Example:

"abcdef1234567890"

​
url
string<uri>
required

Hosted verification URL to redirect the end user to. The URL embeds the session_token and, if configured, uses your white-label domain.

Example:

"https://verify.didit.me/session/abcdef1234567890"

​
status
enum<string>
required

Current status of the session. Newly created sessions return Not Started. If a non-finished session already existed for the same (workflow_id, vendor_data), the returned status reflects that existing session.

Available options:
Not Started,
In Progress,
Approved,
Declined,
In Review,
Expired,
Abandoned,
Kyc Expired,
Resubmitted,
Awaiting User
Example:

"Not Started"

​
workflow_id
string<uuid>
required

Stable workflow identifier (the workflow group, not a specific version) the session was created with.

Example:

"11111111-2222-3333-4444-555555555555"

​
vendor_data
string | null

Identifier you passed in the request to link the session to a user or business in your own system. Echoed back verbatim. Null when not provided.

Example:

"user-123"

​
metadata
object

Arbitrary JSON payload you stored with the session at creation time. Echoed back verbatim. Not shown to the end user. Always present in responses; null when not provided at creation time.

Example:
{
  "user_type": "premium",
  "account_id": "ABC123"
}
​
callback
string<uri> | null

Final redirect URL the user is sent to after completing the flow. Didit appends ?verificationSessionId={session_id}&status={status} to this URL.

Example:

"https://example.com/verification/callback"

​
workflow_version
integer | null

Published version number of the workflow used for this session. Returned alongside workflow_id so you can pin behavior.

Example:

3