Skip to main content
POST
/
v3
/
session
Create Session
curl --request POST \
  --url https://verification.didit.me/v3/session/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "workflow_id": "<string>",
  "vendor_data": "<string>",
  "callback": "<string>",
  "callback_method": "initiator",
  "metadata": "<string>",
  "language": "en",
  "contact_details": {
    "email": "<string>",
    "send_notification_emails": false,
    "email_lang": "en",
    "phone": "<string>"
  },
  "expected_details": {
    "first_name": "<string>",
    "last_name": "<string>",
    "date_of_birth": "2023-12-25",
    "gender": null,
    "nationality": "<string>",
    "country": "<string>",
    "address": "<string>",
    "identification_number": "<string>",
    "ip_address": "127.0.0.1"
  },
  "portrait_image": "<string>"
}
'
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "user-123",
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "status": "Not Started",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "callback": "https://example.com/verification/callback",
  "url": "https://verify.didit.me/session/abcdef123456"
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
workflow_id
string
required

The verification workflow to use. You can check how to create a custom workflow and obtain the workflow_id in the Workflows page.

​
vendor_data
string

A unique identifier for the vendor or user, such as a UUID or email. This field enables proper session tracking and user data aggregation across multiple verification sessions.

​
callback
string

URL to redirect the user after verification completes. Didit automatically appends verificationSessionId and status (Approved, Declined, In Review) as query parameters.

​
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
​
metadata
string

Additional data to store with the session not displayed to the user. For example: {"user_type": "premium", "account_id": "ABC123"}.

​
language
enum<string> | null

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,
ca,
cnr,
cs,
da,
de,
el,
es,
et,
fa,
fi,
fr,
he,
hi,
hr,
hu,
hy,
id,
it,
ja,
ka,
ko,
lt,
lv,
mk,
ms,
nl,
no,
pl,
pt-BR,
pt,
ro,
ru,
sk,
sl,
so,
sr,
sv,
th,
tr,
uk,
uz,
vi,
zh-CN,
zh-TW,
zh
​
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.

​
expected_details
object

Expected user details for cross-validation with extracted verification data.

​
portrait_image
string

A Base64 encoded portrait image of the user's face, with a maximum size of 1MB. This image is only required for Biometric Authentication workflow types that have face match active to perform facial matching against the face captured during the liveness check.

Response

Created

​
session_id
string<uuid>

Unique identifier for the session.

​
session_number
integer

Sequential number assigned to the session.

​
session_token
string

Token used to access the verification flow URL.

​
vendor_data
string

Identifier provided by the vendor for tracking.

​
metadata
object

Additional data associated with the session.

​
status
string

Current status of the verification session.

​
workflow_id
string<uuid>

Identifier of the workflow used for the session.

​
callback
string<uri>

Callback URL to redirect the user after completion.

​
url
string<uri>

URL for the user to complete the verification flow.