Get Workflow State
curl --request GET \
--url https://api.deepidv.com/v1/sessions/{session_id}/workflowimport requests
url = "https://api.deepidv.com/v1/sessions/{session_id}/workflow"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.deepidv.com/v1/sessions/{session_id}/workflow', 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/{session_id}/workflow",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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/{session_id}/workflow"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.deepidv.com/v1/sessions/{session_id}/workflow")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deepidv.com/v1/sessions/{session_id}/workflow")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"status": "PENDING",
"session_progress": "STARTED",
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "COMPLETED",
"attempts": 1,
"started_at": "2026-09-08T14:02:11.000Z",
"completed_at": "2026-09-08T14:03:47.000Z",
"failure_reason": null,
"requirements": {
"document": {
"require_front_only": false,
"front_only_document_types": ["passport"],
"require_secondary_id": false,
"require_tertiary_id": false,
"valid_id_types": ["driver-license-us", "passport-us"],
"valid_states": ["NY", "CA"]
},
"face": { "face_front_photo_only": true }
}
},
{
"step_id": "FACE_LIVENESS",
"status": "PENDING",
"attempts": 0,
"started_at": null,
"completed_at": null,
"failure_reason": null,
"requirements": {
"challenge_type": "FaceMovementChallenge",
"confidence_threshold": 70
}
}
],
"current_step": 1,
"attempts_remaining": 2
}
Workflow Runner
Get Workflow State
Read the current execution state of a workflow session
GET
/
v1
/
sessions
/
{session_id}
/
workflow
Get Workflow State
curl --request GET \
--url https://api.deepidv.com/v1/sessions/{session_id}/workflowimport requests
url = "https://api.deepidv.com/v1/sessions/{session_id}/workflow"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.deepidv.com/v1/sessions/{session_id}/workflow', 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/{session_id}/workflow",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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/{session_id}/workflow"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.deepidv.com/v1/sessions/{session_id}/workflow")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deepidv.com/v1/sessions/{session_id}/workflow")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"status": "PENDING",
"session_progress": "STARTED",
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "COMPLETED",
"attempts": 1,
"started_at": "2026-09-08T14:02:11.000Z",
"completed_at": "2026-09-08T14:03:47.000Z",
"failure_reason": null,
"requirements": {
"document": {
"require_front_only": false,
"front_only_document_types": ["passport"],
"require_secondary_id": false,
"require_tertiary_id": false,
"valid_id_types": ["driver-license-us", "passport-us"],
"valid_states": ["NY", "CA"]
},
"face": { "face_front_photo_only": true }
}
},
{
"step_id": "FACE_LIVENESS",
"status": "PENDING",
"attempts": 0,
"started_at": null,
"completed_at": null,
"failure_reason": null,
"requirements": {
"challenge_type": "FaceMovementChallenge",
"confidence_threshold": 70
}
}
],
"current_step": 1,
"attempts_remaining": 2
}
GET /v1/sessions/{session_id}/workflow
This is a read-only endpoint — it never mutates session or step state.
Request
Headers
| Header | Required | Description |
|---|---|---|
x-api-key | Yes | Your organization’s API key |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string (uuid) | Yes | The session to read |
Example request
curl https://api.deepidv.com/v1/sessions/80e801af-991b-425c-96fc-f5e07d794253/workflow \
-H "x-api-key: YOUR_API_KEY"
const response = await fetch(
"https://api.deepidv.com/v1/sessions/80e801af-991b-425c-96fc-f5e07d794253/workflow",
{ headers: { "x-api-key": "YOUR_API_KEY" } }
);
const state = await response.json();
import requests
response = requests.get(
"https://api.deepidv.com/v1/sessions/80e801af-991b-425c-96fc-f5e07d794253/workflow",
headers={"x-api-key": "YOUR_API_KEY"},
)
state = response.json()
Response
This response shape is distinct from Create Workflow Session’s — it has no
expires_at, and adds status, session_progress, and attempts_remaining. Start Workflow returns this same shape.200 — Success
| Field | Type | Description |
|---|---|---|
session_id | string (uuid) | The session’s ID |
status | string | Session status: PENDING, SUBMITTED, VERIFIED, REJECTED, VOIDED, EXPIRED, or FAILED |
session_progress | string | PENDING, STARTED, or COMPLETED |
steps | array | One step object per workflow step |
current_step | integer | null | 0-based index of the step to submit next. null once the run has finished (all steps completed, or the session became terminal) |
attempts_remaining | number | null | Session-wide failure budget remaining. null when the workflow has no failure limit configured |
steps[] object
| Field | Type | Description |
|---|---|---|
step_id | string | ID_VERIFICATION or FACE_LIVENESS |
status | string | PENDING, IN_PROGRESS, COMPLETED, FAILED, or SKIPPED |
attempts | integer | Number of times this step has been submitted |
started_at | string | null | ISO 8601 timestamp of the first submission, or null |
completed_at | string | null | ISO 8601 timestamp the step reached a terminal status, or null |
failure_reason | string | null | Reason the step last failed, or null. See Submit Workflow Step for the full list of values |
requirements | object | Same shape as in Create Workflow Session |
Error responses
| Status | Description |
|---|---|
400 | Invalid session_id path parameter |
401 | Invalid or missing API key |
403 | The session belongs to a different organization |
404 | Session not found, or no workflow execution state exists for this session |
429 | Too many requests |
{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"status": "PENDING",
"session_progress": "STARTED",
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "COMPLETED",
"attempts": 1,
"started_at": "2026-09-08T14:02:11.000Z",
"completed_at": "2026-09-08T14:03:47.000Z",
"failure_reason": null,
"requirements": {
"document": {
"require_front_only": false,
"front_only_document_types": ["passport"],
"require_secondary_id": false,
"require_tertiary_id": false,
"valid_id_types": ["driver-license-us", "passport-us"],
"valid_states": ["NY", "CA"]
},
"face": { "face_front_photo_only": true }
}
},
{
"step_id": "FACE_LIVENESS",
"status": "PENDING",
"attempts": 0,
"started_at": null,
"completed_at": null,
"failure_reason": null,
"requirements": {
"challenge_type": "FaceMovementChallenge",
"confidence_threshold": 70
}
}
],
"current_step": 1,
"attempts_remaining": 2
}