Creating a Verification Session
To create a verification session, send a POST
request to the /v2/session/
endpoint using a valid client access token obtained through the authentication process.
- Base URL:
https://verification.didit.me
- Endpoint:
/v2/session/
- Method:
POST
- Authentication:
Client Token (Bearer Token)
The authentication endpoint uses a different base URL than the verification session endpoints. Ensure you use the correct URLs to avoid connectivity issues.
Request
Follow these steps to create a verification session programmatically:
Step 1: Authenticate
Obtain a valid access_token
by following the Authentication documentation. This token is required in the Authorization
header of your request.
The access_token
is valid for 24 hours. You only need to re-authenticate once it expires.
Step 2: Prepare Request Parameters
Include the following parameters in the JSON request body:
Parameter | Type | Required? | Description | Example Value |
---|---|---|---|---|
|
| Yes | The verification workflow to use. See Verification Workflows for options. | "11111111-2222-3333-4444-555555555555" |
|
| Optional (Required for biometric_authentication based workflows) | 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. | "user-123" , "john.doe@example.com" |
|
| Optional (Recommended for Web App workflows) | URL to redirect the user after verification completes. | "https://example.com/verification/callback (opens in a new tab)" |
|
| Optional | Additional data to store with the session. | {"user_type": "premium", "account_id": "ABC123"} |
|
| Optional | 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. | See structure below |
|
| Optional | Expected user details for cross-validation with extracted verification data. See details below. | See structure below |
contact_details
Structure
The contact_details
object contains user contact information that can be used for multiple purposes throughout the verification flow:
email
:string
- Email address of the userfor sending verification status notifications for sessions requiring manual review (e.g.,"john.doe@example.com"
). Helps users return to your application once their verification is complete.email_lang
:string
- Language code (ISO 639-1) for email notifications. Controls the language of all email communications (e.g.,"en"
,"es"
,"fr"
)phone
:string
- Phone number in E.164 format (e.g.,"+14155552671"
) that will be used during PHONE_VERIFICATION steps. If not provided, the user will to provide it during the verification flow.
expected_details
Structure
The expected_details
object allows cross-validation of provided data against extracted data during verification. Include only the fields you want to validate:
first_name
:string
(e.g.,"John"
)last_name
:string
(e.g.,"Doe"
)date_of_birth
:string
(Format:YYYY-MM-DD
, e.g.,"1990-05-15"
)gender
:string
(e.g.,"M"
,"F"
)nationality
:string
(ISO 3166-1 alpha-3 country code representing the applicant's country of origin, e.g.,"USA"
)country
:string
(ISO 3166-1 alpha-3 country code representing the country of the applicant's ID document, which may differ from nationality, e.g.,"GBR"
)address
:string
(e.g.,"123 Main St, San Francisco, CA 94105, USA"
)
Step 3: Send the Request
Make a POST
request to /v2/session/
with the prepared parameters.
Example Request
POST /v2/session/ HTTP/1.1
Host: verification.didit.me
Content-Type: application/json
Authorization: Bearer {access_token}
{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"metadata": {
"user_type": "premium"
},
"contact_details": {
"email": "john.doe@example.com",
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"gender": "M",
"nationality": "USA",
"country": "GBR",
"address": "123 Main St, San Francisco, CA 94105, USA"
}
}
Response
The response includes a URL for user redirection:
{
"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"
}
Response Fields
Field | Type | Description |
---|---|---|
|
| Unique identifier for the session. |
|
| Sequential number assigned to the session. |
|
| Token used in the verification workflow. |
|
| Echo of the provided vendor_data. |
|
| Echo of the provided metadata. |
|
| Current session status (e.g., "Not Started"). |
|
| Echo of the provided workflow_id. |
|
| Echo of the provided callback URL. |
|
| Verification URL for user redirection. |
Error Handling
Status Code | Error | Description |
---|---|---|
401 | Unauthorized | Invalid or missing access_token. |
400 | Bad Request | Missing workflow_id or invalid parameters. |
400 | Bad Request | The workflow requires a paid plan subscription. |
Example Error Response
{
"detail": "You need to have a paid plan to perform this workflow."
}
Cross-Validation with expected_details
When expected_details
is provided:
- The system cross-validates it with data extracted during verification
- Discrepancies are raised as warnings
- Depending on the application custom settings, the session may be rejected or approved if discrepancies are found
Use expected_details
selectively to balance accuracy and user conversion rates. Only include fields you need to validate.
Examples of Cross-Validation
- Personal Details:
expected_details.first_name
,expected_details.last_name
,expected_details.date_of_birth
,expected_details.gender
,expected_details.nationality
andexpected_details.country
are checked against document data - Address:
expected_details.address
is compared to proof of address documents
Biometric Authentication Requirements
When using the biometric_authentication
based workflows:
For biometric authentication to work properly:
- The
vendor_data
parameter is required to identify the user - The user must have at least one previous approved verification session that included a liveness check
- The same
vendor_data
value must be used across all sessions for the same user
The biometric authentication workflow allows returning users to verify their identity through facial recognition, without repeating the full KYC process.
Contact Information Usage
- phone: If provided, the user must verify this specific number during Phone Verification (if in the workflow)
- email: If provided and notifications are enabled in Verification Settings, status updates are sent to this email
- email_lang: Sets the language for email notifications (e.g., "es" for Spanish). You can check our supported languages here. Default:
"en"
Next Steps
After receiving the response:
- Redirect the user to the
url
or display it as a QR code - Configure webhooks for real-time status updates
Code Examples
import fetch from 'node-fetch';
// Function to get client token (implement according to Authentication API)
async function getClientToken() {
// Implementation details in Authentication API documentation
// ...
}
async function createSession(
access_token,
workflow_id,
vendor_data,
callback = null,
metadata = null,
email = null,
email_lang = null,
phone = null,
expected_details = null
) {
const url = "https://verification.didit.me/v2/session/";
// Prepare request body
const body = { workflow_id, vendor_data };
if (callback) body.callback = callback;
if (metadata) body.metadata = metadata;
if (email) body.contact_details = { email, email_lang, phone };
if (expected_details) body.expected_details = expected_details;
const requestOptions = {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${access_token}`,
},
body: JSON.stringify(body),
};
try {
const response = await fetch(url, requestOptions);
const data = await response.json();
if (!response.ok) {
throw new Error(data.detail || "Failed to create session");
}
return data;
} catch (error) {
console.error("Error:", error.message);
throw error;
}
}
// Example usage
async function createSessionFlow(workflow_id, vendor_data) {
try {
// 1. Get client token
const token = await getClientToken();
if (!token) {
throw new Error("Failed to fetch client token");
}
// 2. Create session
const session = await createSession(token.access_token, workflow_id, vendor_data);
// Redirect user to the session URL
if (session.url) {
console.log(`Redirect user to: ${session.url}`);
// window.location.href = session.url;
}
return session;
} catch (error) {
console.error("Session creation failed:", error);
}
}