Start Workflow
curl --request POST \
--url https://api.deepidv.com/v1/sessions/{session_id}/workflow/startimport requests
url = "https://api.deepidv.com/v1/sessions/{session_id}/workflow/start"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.deepidv.com/v1/sessions/{session_id}/workflow/start', 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/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$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/start"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.deepidv.com/v1/sessions/{session_id}/workflow/start")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deepidv.com/v1/sessions/{session_id}/workflow/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"status": "PENDING",
"session_progress": "PENDING",
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "PENDING",
"attempts": 0,
"started_at": null,
"completed_at": null,
"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": 0,
"attempts_remaining": 3
}
{
"error": "Session has already been started or is no longer runnable",
"current_step": null
}
Workflow Runner
Start Workflow
Hand off an un-started workflow session to an SDK runner
POST
/
v1
/
sessions
/
{session_id}
/
workflow
/
start
Start Workflow
curl --request POST \
--url https://api.deepidv.com/v1/sessions/{session_id}/workflow/startimport requests
url = "https://api.deepidv.com/v1/sessions/{session_id}/workflow/start"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.deepidv.com/v1/sessions/{session_id}/workflow/start', 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/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$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/start"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.deepidv.com/v1/sessions/{session_id}/workflow/start")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deepidv.com/v1/sessions/{session_id}/workflow/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"status": "PENDING",
"session_progress": "PENDING",
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "PENDING",
"attempts": 0,
"started_at": null,
"completed_at": null,
"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": 0,
"attempts_remaining": 3
}
{
"error": "Session has already been started or is no longer runnable",
"current_step": null
}
POST /v1/sessions/{session_id}/workflow/start
You don’t need to call this endpoint before submitting steps — it’s a convenience check. Submit Workflow Step performs the same validity checks itself.
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 start |
Example request
curl -X POST https://api.deepidv.com/v1/sessions/80e801af-991b-425c-96fc-f5e07d794253/workflow/start \
-H "x-api-key: YOUR_API_KEY"
const response = await fetch(
"https://api.deepidv.com/v1/sessions/80e801af-991b-425c-96fc-f5e07d794253/workflow/start",
{ method: "POST", headers: { "x-api-key": "YOUR_API_KEY" } }
);
const state = await response.json();
import requests
response = requests.post(
"https://api.deepidv.com/v1/sessions/80e801af-991b-425c-96fc-f5e07d794253/workflow/start",
headers={"x-api-key": "YOUR_API_KEY"},
)
state = response.json()
Response
200 — Success
Returns the same execution-state envelope as Get Workflow State —session_id, status, session_progress, steps, current_step, attempts_remaining.
Error responses
| Status | Description |
|---|---|
400 | Invalid session_id path parameter, or the session’s workflow contains a step type not supported by the Workflow Runner API (response includes invalid_steps) |
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 |
409 | The session has already been started, or is no longer runnable (not PENDING) |
429 | Too many requests |
{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"status": "PENDING",
"session_progress": "PENDING",
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "PENDING",
"attempts": 0,
"started_at": null,
"completed_at": null,
"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": 0,
"attempts_remaining": 3
}
{
"error": "Session has already been started or is no longer runnable",
"current_step": null
}