Create Session

curl --request POST \
  --url https://api.deepidv.com/v1/sessions

import requests

url = "https://api.deepidv.com/v1/sessions"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.deepidv.com/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.deepidv.com/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.deepidv.com/v1/sessions"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.deepidv.com/v1/sessions")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.deepidv.com/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_url": "https://verify.deepidv.com/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890?oid=your-org-id&redirect_url=https%3A%2F%2Fyourapp.com%2Fverify-callback",
  "externalId": "user-12345",
  "links": [
    {
      "rel": "admin_console",
      "href": "https://app.deepidv.com/dashboard/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Click this link to view this session in your DeepIDV admin console"
    },
    {
      "rel": "session_details",
      "href": "https://api.deepidv.com/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Use this ref to fetch the session details"
    }
  ]
}

POST

sessions

Create Session

curl --request POST \
  --url https://api.deepidv.com/v1/sessions

import requests

url = "https://api.deepidv.com/v1/sessions"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.deepidv.com/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.deepidv.com/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.deepidv.com/v1/sessions"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.deepidv.com/v1/sessions")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.deepidv.com/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_url": "https://verify.deepidv.com/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890?oid=your-org-id&redirect_url=https%3A%2F%2Fyourapp.com%2Fverify-callback",
  "externalId": "user-12345",
  "links": [
    {
      "rel": "admin_console",
      "href": "https://app.deepidv.com/dashboard/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Click this link to view this session in your DeepIDV admin console"
    },
    {
      "rel": "session_details",
      "href": "https://api.deepidv.com/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Use this ref to fetch the session details"
    }
  ]
}

POST /v1/sessions

Creates a new identity verification session and optionally sends email and SMS invitations to the applicant.

Request

Headers

Header	Required	Description
`x-api-key`	Yes	Your API key
`Content-Type`	Yes	`application/json`

Body parameters

Both camelCase and snake_case parameter names are accepted. If both are provided for the same field, the camelCase value takes priority.

Parameter	Alias	Type	Required	Description
`first_name`	`firstName`	string	Yes	Applicant’s first name
`last_name`	`lastName`	string	Yes	Applicant’s last name
`email`	—	string	Yes	Applicant’s email address
`phone`	—	string	Yes	Applicant’s phone number in E.164 format (e.g. `+15192223333`)
`external_id`	`externalId`	string	No	Your internal reference ID for this session
`send_email_invite`	`sendEmailInvite`	boolean	No	Send an email invitation to the applicant. Defaults to `true`
`send_phone_invite`	`sendPhoneInvite`	boolean	No	Send an SMS invitation to the applicant. Defaults to `true`
`workflow_id`	`workflowId`	string	No	ID of the workflow to use. If omitted, runs as a standalone verification
`redirect_url`	`redirectUrl`	string	No	HTTPS URL to redirect the end-user to after the verification session ends. Must be a valid HTTPS URL
`expires_in_hours`	`expiresInHours`	integer	No	Auto-expire the session after this many hours (1-8760). Overrides the workflow’s expiry setting if both are provided. If omitted, the workflow’s expiry setting is used (if configured)

Example request

curl -X POST https://api.deepidv.com/v1/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+15192223333",
    "external_id": "user-12345",
    "workflow_id": "wf_abc123",
    "redirect_url": "https://yourapp.com/verify-callback",
    "expires_in_hours": 48
  }'

const response = await fetch("https://api.deepidv.com/v1/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
    phone: "+15192223333",
    external_id: "user-12345",
    workflow_id: "wf_abc123",
    redirect_url: "https://yourapp.com/verify-callback",
    expires_in_hours: 48,
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.deepidv.com/v1/sessions",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone": "+15192223333",
        "external_id": "user-12345",
        "workflow_id": "wf_abc123",
        "redirect_url": "https://yourapp.com/verify-callback",
        "expires_in_hours": 48,
    },
)

Response

200 — Success

Field	Type	Description
`id`	string	Unique identifier for the created session
`session_url`	string	Base URL where the applicant completes verification
`externalId`	string	Your external ID (only returned if provided in the request)
`expires_at`	string	ISO 8601 timestamp when the session will auto-expire (only present if expiry is configured)
`links`	array	Associated verification links

Error responses

Status	Description
`400 Bad Request`	Invalid request body — check required fields and phone format
`401 Unauthorized`	Missing or invalid API key
`402 Payment Required`	Insufficient token balance
`404 Not Found`	Workflow ID not found
`429 Too Many Requests`	Rate limit exceeded

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_url": "https://verify.deepidv.com/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890?oid=your-org-id&redirect_url=https%3A%2F%2Fyourapp.com%2Fverify-callback",
  "externalId": "user-12345",
  "links": [
    {
      "rel": "admin_console",
      "href": "https://app.deepidv.com/dashboard/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Click this link to view this session in your DeepIDV admin console"
    },
    {
      "rel": "session_details",
      "href": "https://api.deepidv.com/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Use this ref to fetch the session details"
    }
  ]
}

Redirect URL

When a redirect_url is provided in the request, the returned session_url will include it as an encoded query parameter:

https://verify.deepidv.com/session/<session_id>?oid=<org_id>&redirect_url=https%3A%2F%2Fyourapp.com%2Fverify-callback

Upon session completion, failure, or user exit, the verification app will redirect the end-user back to your redirect_url with the following query parameters appended:

Parameter	Type	Description
`session_id`	string	The session ID
`status`	string	The outcome of the session
`reason`	string	Additional context for the outcome (omitted when status is `success`)

Status values

Value	Description
`success`	Verification session was completed and submitted successfully
`failed`	Session encountered an error during the verification process
`abandoned`	User manually exited the session without completing
`expired`	Session was automatically expired before the user completed verification

Reason values

Value	Description
`document_unreadable`	The uploaded ID document could not be processed (blurry, glare, wrong doc type, etc.)
`face_mismatch`	Liveness/selfie did not match the document photo
`session_expired`	The session timed out before the user completed verification
`internal_error`	An unexpected server-side error occurred
`user_cancelled`	User explicitly chose to leave/cancel the verification
`unknown`	Catch-all for any unclassified failure

The reason parameter is omitted when status=success. When status=abandoned, the reason will typically be user_cancelled. New reason values may be added in the future — your integration should handle unknown reasons gracefully.

Example redirect URLs

# Success
https://yourapp.com/verify-callback?session_id=sess_abc&status=success

# Failure
https://yourapp.com/verify-callback?session_id=sess_abc&status=failed&reason=document_unreadable

# Abandoned
https://yourapp.com/verify-callback?session_id=sess_abc&status=abandoned&reason=user_cancelled

# Expired
https://yourapp.com/verify-callback?session_id=sess_abc&status=expired&reason=session_expired

OpenAPI Specification Retrieve Session

Specifications

Sessions

Credit Check

Financial

Management API 🔧

Silent Screening

Async Jobs

Server-to-Server

Sandbox

Create Session

Request

Headers

Body parameters

Example request

Response

200 — Success

Error responses

Redirect URL

Status values

Reason values

Example redirect URLs

​Request

​Headers

​Body parameters

​Example request

​Response

​200 — Success

​Error responses

​Redirect URL

​Status values

​Reason values

​Example redirect URLs

Request

Headers

Body parameters

Example request

Response

200 — Success

Error responses

Redirect URL

Status values

Reason values

Example redirect URLs