Skip to main content
POST
https://api.deepidv.com
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.deepidv.com/v1/sessions
{
  "idv_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

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

​
Response

​
200 — Success

FieldTypeDescription
idv_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
{
  "idv_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_url": "https://app.deepidv.com",
  "externalId": "user-12345",
  "links": []
}