Skip to main content
GET
https://api.deepidv.com
/
v1
/
sessions
List Sessions
curl --request GET \
  --url https://api.deepidv.com/v1/sessions
{
  "sessions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "org_abc123",
      "user_id": "usr_def456",
      "sender_user_id": "usr_ghi789",
      "status": "VERIFIED",
      "type": "session",
      "session_progress": "COMPLETED",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:45:00.000Z"
    }
  ],
  "next_token": "eyJpZCI6ImFiYzEyMyJ9"
}

GET /v1/sessions
Returns a paginated list of verification sessions. By default, returns sessions created by the authenticated user. Use query parameters to list by organization or filter by external ID.

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key

​
Query parameters

ParameterTypeRequiredDefaultDescription
limitnumberNo50Number of sessions to return (1–500)
next_tokenstringNo—Pagination token from a previous response
start_datestringNo—Filter sessions created on or after this date (ISO 8601)
end_datestringNo—Filter sessions created on or before this date (ISO 8601)
by_organizationbooleanNofalseWhen true, returns all sessions for your organization instead of only those you created
external_idstringNo—Filter sessions by your external reference ID
workflow_idstringNo—Filter sessions by workflow ID
Query modes are evaluated in priority order: external_id > workflow_id > by_organization > default sender-based query.

​
Example requests

​
List your sessions (default)

curl -X GET "https://api.deepidv.com/v1/sessions?limit=25&start_date=2025-01-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

​
List all organization sessions

curl -X GET "https://api.deepidv.com/v1/sessions?by_organization=true&limit=100" \
  -H "x-api-key: YOUR_API_KEY"

​
Filter by workflow ID

curl -X GET "https://api.deepidv.com/v1/sessions?workflow_id=wf_abc123" \
  -H "x-api-key: YOUR_API_KEY"

​
Filter by external ID

curl -X GET "https://api.deepidv.com/v1/sessions?external_id=user-12345" \
  -H "x-api-key: YOUR_API_KEY"

​
Response

​
200 — Success

FieldTypeDescription
sessionsarrayArray of session objects (see Retrieve Session for full field reference)
next_tokenstring | nullPagination token to fetch the next page. null when no more results

​
Pagination

To fetch the next page of results, pass the next_token from the response as a query parameter: 
curl -X GET "https://api.deepidv.com/v1/sessions?limit=25&next_token=eyJpZCI6ImFiYzEyMyJ9" \
  -H "x-api-key: YOUR_API_KEY"
Continue paginating until next_token is null.

​
Error responses

StatusDescription
400 Bad RequestInvalid query parameters (e.g., limit out of range, invalid date format, invalid next_token)
401 UnauthorizedMissing or invalid API key
429 Too Many RequestsRate limit exceeded
{
  "sessions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "org_abc123",
      "user_id": "usr_def456",
      "sender_user_id": "usr_ghi789",
      "status": "VERIFIED",
      "type": "session",
      "session_progress": "COMPLETED",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:45:00.000Z"
    }
  ],
  "next_token": "eyJpZCI6ImFiYzEyMyJ9"
}