Skip to main content
POST
/
v3
/
session
/
cURL
curl -X POST 'https://verification.didit.me/v3/session/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -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": "3FaJ9wLqX2Mz",
  "url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
  "vendor_data": "user-123",
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "status": "Not Started",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "workflow_version": 3,
  "callback": "https://example.com/verification/callback"
}

​
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

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
any

Arbitrary JSON stored with the session and echoed back in the response and webhooks. Any JSON value is accepted (object, string, number, array), but a JSON object of key/value pairs is recommended. 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,
mn,
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. Ignored for Business Verification (KYB) workflows.

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, or TIFF). 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. Ignored for other workflow types.

Example:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="

Response

Session created (or returned, if an unfinished session with the same vendor_data already exists on the workflow's latest published version). 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

12-character URL-safe token that authorizes the end user to access the hosted verification flow at url. Valid until the session expires. Treat it as a secret — anyone holding it can open the verification flow for this session.

Example:

"3FaJ9wLqX2Mz"

​
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. When the request includes language, the URL contains a language path segment — https://verify.didit.me/{language}/session/{session_token} (e.g. /es/session/...); without language, the segment is omitted.

Example:

"https://verify.didit.me/session/3FaJ9wLqX2Mz"

​
vendor_data
string | null
required

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
any
required

Arbitrary JSON payload you stored with the session at creation time. Echoed back verbatim — whatever JSON value you sent (object, string, number, array) is returned as-is, though a JSON object is recommended. Not shown to the end user. Always present in responses; null when not provided at creation time.

Example:
{
  "user_type": "premium",
  "account_id": "ABC123"
}
​
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 vendor_data on the workflow's latest published version, 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"

​
callback
string<uri> | null
required

Final redirect URL the user is sent to after completing the flow. Didit appends ?verificationSessionId={session_id}&status={status} to this URL. Falls back to the workflow's configured callback URL when not provided in the request; null when neither is set.

Example:

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

​
workflow_id
string<uuid>
required

Stable identifier of the workflow this session runs on. Always the workflow's stable group identifier — even if you referenced a specific workflow version UUID in the request (backward-compatible lookup), the response carries the stable workflow_id. Use it to correlate the session with the workflow you configured in the Console.

Example:

"11111111-2222-3333-4444-555555555555"

​
workflow_version
integer
required

Version number of the published workflow version the session was pinned to at creation. Didit resolves workflow_id to the workflow's latest published version when the session is created, and the session keeps running that version even if the workflow is republished later.

Example:

3