Skip to main content
POST
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.deepidv.com/v1/sessions
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_url": "https://app.deepidv.com",
  "externalId": "user-12345",
  "links": []
}

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

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key
Content-TypeYesapplication/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.
ParameterAliasTypeRequiredDescription
first_namefirstNamestringYesApplicant’s first name
last_namelastNamestringYesApplicant’s last name
email—stringYesApplicant’s email address
phone—stringYesApplicant’s phone number in E.164 format (e.g. +15192223333)
external_idexternalIdstringNoYour internal reference ID for this session
send_email_invitesendEmailInvitebooleanNoSend an email invitation to the applicant. Defaults to true
send_phone_invitesendPhoneInvitebooleanNoSend an SMS invitation to the applicant. Defaults to true
workflow_idworkflowIdstringNoID of the workflow to use. If omitted, runs as a standalone verification
redirect_urlredirectUrlstringNoHTTPS URL to redirect the end-user to after the verification session ends. Must be a valid HTTPS URL

​
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"
  }'

​
Response

​
200 — Success

FieldTypeDescription
idstringUnique identifier for the created session
session_urlstringBase URL where the applicant completes verification
externalIdstringYour external ID (only returned if provided in the request)
linksarrayAssociated verification links

​
Error responses

StatusDescription
400 Bad RequestInvalid request body — check required fields and phone format
401 UnauthorizedMissing or invalid API key
402 Payment RequiredInsufficient token balance
404 Not FoundWorkflow ID not found
429 Too Many RequestsRate limit exceeded
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_url": "https://app.deepidv.com",
  "externalId": "user-12345",
  "links": []
}

​
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:
ParameterTypeDescription
session_idstringThe session ID
statusstringThe outcome of the session
reasonstringAdditional context for the outcome (omitted when status is success)

​
Status values

ValueDescription
successVerification session was completed and submitted successfully
failedSession encountered an error during the verification process
abandonedUser manually exited the session without completing

​
Reason values

ValueDescription
document_unreadableThe uploaded ID document could not be processed (blurry, glare, wrong doc type, etc.)
face_mismatchLiveness/selfie did not match the document photo
session_expiredThe session timed out before the user completed verification
internal_errorAn unexpected server-side error occurred
user_cancelledUser explicitly chose to leave/cancel the verification
unknownCatch-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