Verification Service Methods

This section highlights the different methods that can be used to create and retrieve verficiation resources through the DeepIDV API.

Create IDV Session
Fetch IDV Sessions
Fetch IDV Sessions by External ID
Fetch IDV Sessions by Organization ID
Fetch IDV Session by ID
Error Status Reference

Create Idv Session

Request to Create and send an IDV session to an applicant

Request

POST /idv

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Body Parameters

Type	Params	Values	Description
BODY	email*	string	The end users email (IDV session will be sent to this email)
BODY	firstName*	string	The end users first name
BODY	lastName*	string	The end users last name
BODY	phone*	string	The end users phone number (with country code) Example: +15192223333
BODY	workflowId	string	The predefined workflow to send out the session as
BODY	externalId	string	A unique identifier that can be used to retrieve the generated idv session
BODY	sendEmailInvite	boolean	Send an email to the applicant (DEFAULT: true)
BODY	sendPhoneInvite	boolean	Send an SMS to the applicant (DEFAULT: true)

Example Request

{
  "email": "applicant@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+15192223333",
  "externalId": "external-123",
  "sendEmailInvite": true,
  "sendPhoneInvite": true
}

Response

Success (200)

{
  "id": "<idv_id>",
  "url": "<session_url>",
  "externalId": "<external_id>",
  "links": "<links>"
}

Response Fields

Field	Type	Description
idv_id	string	The unique id for the created idv session
session_url	string	The link created to complete the idv session
external_id	string	The externalId that was passed as a parameter
links	array	A list of discoverable URLs for related resources

Best Practices

Always validate required fields before sending requests
Store the id and externalId for future reference
Handle error responses appropriately in your application

Fetch Idv Sessions

Get all IDV sessions sent by the User attached to the API Key. Returned in DESCENDING order by createdAt date (date sent).

Request

GET /idv

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Query Parameters

Type	Params	Values	Description
QUERY	limit	string	The limit of IDV session to return (DEFAULT: 50, MAX: 500)
QUERY	nextToken	string	To retrieve the next page of sessions, provided the limit was reached in a previous call
QUERY	startDate	string ($ISO date)	Start date for the search range (Example: 2025-05-19)
QUERY	endDate	string ($ISO date)	End date for the search range (Example: 2025-06-30)

Response

Success (200)

{
  "sessions": [
    {
      "id": "<idv_id>",
      "url": "<session_url>",
      "externalId": "<external_id>",
      "applicant": "<applicant>",
      "status": "<status>",
      "submittedAt": "<submitted_at>",
      "createdAt": "<created_at>",
      "updatedAt": "<updated_at>"
    }
  ],
  "nextToken": "<next_token>"
}

Response Fields

Field	Type	Description
idv_id	string	The unique id for an idv session
session_url	string	The link for an idv session
external_id	string	The externalId for an idv session
applicant	string	The applicant an idv session was assigned to
status	string	The status of an idv session
submitted_at	string	The date stamp of when a session was submitted
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated
next_token	string	The token to get the next page of sessions (if limit was reached)

Applicant Object

{
  "firstName": "",
  "lastName": "",
  "email": "",
  "phone": ""
}

Status Values

The status field can have one of the following values:

PENDING: Session has not been started
SUBMITTED: Session has been submitted
VERIFIED: Session has been verified
REJECTED: Session has been rejected

Fetch Idv Sessions by External ID

Get all IDV sessions sent with an external id.

Request

GET /idv/externalId/{external_id}

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Response

Success (200)

[
  {
    "id": "<idv_id>",
    "url": "<session_url>",
    "externalId": "<external_id>",
    "applicant": "<applicant>",
    "status": "<status>",
    "sessionProgress": "<session_progress>",
    "submittedAt": "<submitted_at>",
    "createdAt": "<created_at>",
    "updatedAt": "<updated_at>"
  }
]

Response Fields

Field	Type	Description
idv_id	string	The unique id for an idv session
session_url	string	The link for an idv session
external_id	string	The externalId for an idv session
applicant	string	The applicant an idv session was assigned to
status	string	The status of an idv session
session_progress	string	The progress of an idv session
submitted_at	string	The date stamp of when a session was submitted
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated

Applicant Object

{
  "firstName": "",
  "lastName": "",
  "email": "",
  "phone": ""
}

Status Values

The status field can have one of the following values:

PENDING: Session has not been started
SUBMITTED: Session has been submitted
VERIFIED: Session has been verified
REJECTED: Session has been rejected

Session Progress Values

The session_progress fiels can have one of the following values:

STARTED: Session has been started
COMPLETED: Session has been completed
PENDING: Session has not been started

Fetch Idv Sessions by Organization ID

Get's all idv sessions for an organization under the api key. Returned in DESCENDING order by createdAt date (date sent)

Request

GET /idv/org

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Query Parameters

Type	Params	Values	Description
QUERY	limit	string	The limit of IDV session to return (DEFAULT: 50, MAX: 500)
QUERY	nextToken	string	To retrieve the next page of sessions, provided the limit was reached in a previous call
QUERY	startDate	string ($ISO date)	Start date for the search range (Example: 2025-05-19)
QUERY	endDate	string ($ISO date)	End date for the search range (Example: 2025-06-30)

Response

Success (200)

{
  "sessions": [
    {
      "id": "<idv_id>",
      "url": "<session_url>",
      "externalId": "<external_id>",
      "applicant": "<applicant>",
      "status": "<status>",
      "submittedAt": "<submitted_at>",
      "createdAt": "<created_at>",
      "updatedAt": "<updated_at>"
    }
  ],
  "nextToken": "<next_token>"
}

Response Fields

Field	Type	Description
idv_id	string	The unique id for an idv session
session_url	string	The link for an idv session
external_id	string	The externalId for an idv session
applicant	string	The applicant an idv session was assigned to
status	string	The status of an idv session
submitted_at	string	The date stamp of when a session was submitted
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated
next_token	string	The token to get the next page of sessions (if limit was reached)

Applicant Object

{
  "firstName": "",
  "lastName": "",
  "email": "",
  "phone": ""
}

Status Values

The status field can have one of the following values:

PENDING: Session has not been started
SUBMITTED: Session has been submitted
VERIFIED: Session has been verified
REJECTED: Session has been rejected

Fetch Idv Session by ID

Fetches a single IDV session by session ID

Request

GET /idv/{session_id}

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Response

Success (200)

{
  "sessionRecord": {
    "id": "<idv_id>",
    "url": "<session_url>",
    "externalId": "<external_id>",
    "applicant": "<applicant>",
    "status": "<status>",
    "submittedAt": "<submitted_at>",
    "createdAt": "<created_at>",
    "updatedAt": "<updated_at>"
  },
  "resourceLinks": {
    "id_front": "<id_front>",
    "id_back": "<id_back>",
    "selfie_front": "<selfie_front>",
    "selfie_right": "<selfie_right>",
    "selfie_left": "<selfie_left>",
    "facelivness": "<facelivness>",
    "custom-prompts-list_n": "<custom-prompts-list_n>"
  }
}

Response Fields

Field	Type	Description
idv_id	string	The unique id for an idv session
session_url	string	The link for an idv session
external_id	string	The externalId for an idv session
applicant	string	The applicant an idv session was assigned to
status	string	The status of an idv session
submitted_at	string	The date stamp of when a session was submitted
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated
next_token	string	The token to get the next page of sessions (if limit was reached)
id_front	string OR undefined	The presigned url link of id front upload image (60 minute ttl)
id_back	string OR undefined	The presigned url link of id front upload image (60 minute ttl)
selfie_front	string OR undefined	The presigned url link of selfie front upload image (60 minute ttl)
selfie_right	string OR undefined	The presigned url link of selfie right upload image (60 minute ttl)
selfie_left	string OR undefined	The presigned url link of selfie left upload image (60 minute ttl)
facelivess	string OR undefined	The presigned url link of facelivness image result (60 minute ttl)
custom-prompts-list_n	string OR undefined	The presigned url link of custom prompt image result (60 minute ttl, n = prompt number)

Applicant Object

{
  "firstName": "",
  "lastName": "",
  "email": "",
  "phone": ""
}

Status Values

The status field can have one of the following values:

PENDING: Session has not been started
SUBMITTED: Session has been submitted
VERIFIED: Session has been verified
REJECTED: Session has been rejected

Error Status Reference

The DeepIDV API uses standard HTTP status codes to indicate the success or failure of requests. The following table describes the possible error responses you may encounter:

Status Code	Error Message	Description
400	`{"error": "Invalid Input."}`	The request parameters are invalid or missing required fields
401	`{"error": "Invalid API key."}`	The provided API key is invalid or expired
402	`{"error": "Insufficient funds or subscription."}`	Unauthorized - Payment required
403	`{"error": "API key is missing."}`	No API key was provided in the request
429	`{"error": "Rate limit exceeded."}`	Too many requests have been made in a short period
500	`{"error": "Something went wrong."}`	An unexpected error occurred on the server

Best Practices for Error Handling

Always validate required fields before sending requests
Implement retry logic with exponential backoff for rate limit errors (429)
Store error logs for debugging and monitoring purposes
Display user-friendly error messages in your application

Table of Contents​

Create Idv Session​

Request​

Parameters​

Headers​

Body Parameters​

Example Request​

Response​

Success (200)​

Response Fields​

Best Practices​

Fetch Idv Sessions​

Request​

Parameters​

Headers​

Query Parameters​

Response​

Success (200)​

Response Fields​

Applicant Object​

Status Values​

Fetch Idv Sessions by External ID​

Request​

Parameters​

Headers​

Response​

Success (200)​

Response Fields​

Applicant Object​

Status Values​

Session Progress Values​

Fetch Idv Sessions by Organization ID​

Request​

Parameters​

Headers​

Query Parameters​

Response​

Success (200)​

Response Fields​

Applicant Object​

Status Values​

Fetch Idv Session by ID​

Request​

Parameters​

Headers​

Response​

Success (200)​

Response Fields​

Applicant Object​

Status Values​

Error Status Reference​

Best Practices for Error Handling​

Table of Contents

Create Idv Session

Request

Parameters

Headers

Body Parameters

Example Request

Response

Success (200)

Response Fields

Best Practices

Fetch Idv Sessions

Request

Parameters

Headers

Query Parameters

Response

Success (200)

Response Fields

Applicant Object

Status Values

Fetch Idv Sessions by External ID

Request

Parameters

Headers

Response

Success (200)

Response Fields

Applicant Object

Status Values

Session Progress Values

Fetch Idv Sessions by Organization ID

Request

Parameters

Headers

Query Parameters

Response

Success (200)

Response Fields

Applicant Object

Status Values

Fetch Idv Session by ID

Request

Parameters

Headers

Response

Success (200)

Response Fields

Applicant Object

Status Values

Error Status Reference

Best Practices for Error Handling