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>",
    "id_country": "<string>",
    "poa_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"
}
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
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,
bs,
ca,
cnr,
cs,
da,
de,
el,
es,
et,
fa,
fi,
fr,
he,
hi,
hr,
hu,
hy,
id,
it,
ja,
ka,
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
​
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.