🎉 Unlimited Free KYC - Forever!!

Identity Verification
API Reference
Create Session

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:

ParameterTypeRequired?DescriptionExample Value
workflow_idstringYesThe verification workflow to use. See Verification Workflows for options."11111111-2222-3333-4444-555555555555"
vendor_datastringOptional (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"
callbackstringOptional (Recommended for Web App workflows)URL to redirect the user after verification completes."https://example.com/verification/callback (opens in a new tab)"
metadataobjectOptionalAdditional data to store with the session.{"user_type": "premium", "account_id": "ABC123"}
contact_detailsobjectOptionalUser 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
expected_detailsobjectOptionalExpected 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

FieldTypeDescription
session_idstringUnique identifier for the session.
session_numbernumberSequential number assigned to the session.
session_tokenstringToken used in the verification workflow.
vendor_datastringEcho of the provided vendor_data.
metadataobjectEcho of the provided metadata.
statusstringCurrent session status (e.g., "Not Started").
workflow_idstringEcho of the provided workflow_id.
callbackstringEcho of the provided callback URL.
urlstringVerification URL for user redirection.

Error Handling

Status CodeErrorDescription
401UnauthorizedInvalid or missing access_token.
400Bad RequestMissing workflow_id or invalid parameters.
400Bad RequestThe 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 and expected_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:

  1. The vendor_data parameter is required to identify the user
  2. The user must have at least one previous approved verification session that included a liveness check
  3. 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:

  1. Redirect the user to the url or display it as a QR code
  2. 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);
  }
}
import requests
 
# Function to get client token (implement according to Authentication API)
def get_client_token():
    # Implementation details in Authentication API documentation
    # ...
    pass
 
def create_session(
    access_token: str,
    workflow_id: str,
    vendor_data: str,
    callback: str = None,
    metadata: dict = None,
    email: str = None,
    email_lang: str = None,
    phone: str = None,
    expected_details: dict = None
):
    url = "https://verification.didit.me/v2/session/"
 
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}"
    }
 
    body = {"workflow_id": workflow_id, "vendor_data": vendor_data}
    if callback:
        body["callback"] = callback
    if metadata:
        body["metadata"] = metadata
    if email:
        body["contact_details"] = { "email": email, "email_lang": email_lang, "phone": phone }
    if expected_details:
        body["expected_details"] = expected_details
 
    try:
        response = requests.post(url, headers=headers, json=body)
        response.raise_for_status()
        return response.json()
    except requests.RequestException as e:
        error_msg = e.response.json().get('detail', str(e)) if e.response else str(e)
        raise Exception(f"Failed to create session: {error_msg}")
 
# Example usage
def create_session_flow(workflow_id, vendor_data):
    # 1. Get client token
    token = get_client_token()
    if not token:
        raise Exception("Failed to fetch client token")
 
    # 2. Create session
    session = create_session(token["access_token"], workflow_id, vendor_data)
 
    # Redirect user to the session URL or display it as a QR code
    return redirect(session['url'])