> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepidv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Workflow Session
> Create a headless session that runs a workflow through the Workflow Runner API
```
POST /v1/workflows/{workflow_id}/sessions
```
Creates a new session scoped to a workflow and returns the ordered list of steps the session must complete, along with each step's requirements. Unlike [Create Session](/api-reference/sessions/create-session), this endpoint does not send an invite email or SMS and does not return a hosted `session_url` — it's designed for headless integrations (mobile/web SDKs) that drive the session directly through [Submit Workflow Step](/api-reference/workflow-runner/submit-workflow-step).
Only workflows whose steps are all `ID_VERIFICATION` and/or `FACE_LIVENESS` can be run through this API today. See [Available steps](#available-steps) below.
## Request
### Headers
| Header | Required | Description |
| ----------- | -------- | --------------------------- |
| `x-api-key` | Yes | Your organization's API key |
### Path parameters
| Parameter | Type | Required | Description |
| ------------- | ------------- | -------- | ----------------------------- |
| `workflow_id` | string (uuid) | Yes | The ID of the workflow to run |
### Body parameters
Both camelCase and snake\_case parameter names are accepted. If both are provided for the same field, the camelCase value takes priority.
| Parameter | Alias | Type | Required | Description |
| ------------------ | ---------------- | ------- | -------- | -------------------------------------------------------------- |
| `email` | — | string | Yes | Email address of the person completing the session |
| `first_name` | `firstName` | string | Yes | First name of the person completing the session |
| `last_name` | `lastName` | string | Yes | Last name of the person completing the session |
| `phone` | — | string | Yes | Phone number in E.164 format, e.g. `+14155552671` |
| `external_id` | `externalId` | string | No | Your own identifier for this session, echoed back on retrieval |
| `expires_in_hours` | `expiresInHours` | integer | No | Overrides the workflow's default session expiry. `1`-`8760` |
### Example request
```bash cURL theme={null}
curl -X POST https://api.deepidv.com/v1/workflows/29ce15d0-a1b7-4a66-b04e-8ade2b0c1ed0/sessions \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "jane.doe@example.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": "+14155552671",
"external_id": "user_12345"
}'
```
```javascript Node.js theme={null}
const response = await fetch(
"https://api.deepidv.com/v1/workflows/29ce15d0-a1b7-4a66-b04e-8ade2b0c1ed0/sessions",
{
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
email: "jane.doe@example.com",
first_name: "Jane",
last_name: "Doe",
phone: "+14155552671",
external_id: "user_12345",
}),
}
);
const session = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.deepidv.com/v1/workflows/29ce15d0-a1b7-4a66-b04e-8ade2b0c1ed0/sessions",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"email": "jane.doe@example.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": "+14155552671",
"external_id": "user_12345",
},
)
session = response.json()
```
## Response
### 200 — Success
| Field | Type | Description |
| -------------- | -------------- | ----------------------------------------------------------------------------- |
| `session_id` | string (uuid) | The created session's ID |
| `expires_at` | string \| null | ISO 8601 timestamp the session expires at, or `null` if it doesn't expire |
| `steps` | array | Ordered list of [step objects](#steps-object), one per workflow step |
| `current_step` | integer | 0-based index into `steps` of the step to submit next. Always `0` on creation |
### `steps[]` object
| Field | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------------- |
| `step_id` | string | The step's identifier. See [Available steps](#available-steps) |
| `status` | string | `PENDING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`, or `SKIPPED`. Always `PENDING` on creation |
| `requirements` | object | Shape depends on `step_id` — see below |
### Available steps
Only these two step types can be run through the Workflow Runner API. A workflow containing any other step type is rejected — see [Error responses](#error-responses).
| `step_id` | Requirements shape |
| ----------------- | -------------------------------------------------------------- |
| `ID_VERIFICATION` | [ID\_VERIFICATION requirements](#id_verification-requirements) |
| `FACE_LIVENESS` | [FACE\_LIVENESS requirements](#face_liveness-requirements) |
#### ID\_VERIFICATION requirements
| Field | Type | Description |
| ------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document.require_front_only` | boolean | Always `false` at this point — no `document_type` has been chosen yet. Once the client selects a document type, check it against `front_only_document_types` before deciding whether to capture a back image |
| `document.front_only_document_types` | string\[] | Document types that never require a back-of-document image, e.g. `["passport"]` |
| `document.require_secondary_id` | boolean | Whether a second identity document must also be submitted |
| `document.require_tertiary_id` | boolean | Whether a third identity document must also be submitted |
| `document.valid_id_types` | string\[] | Document types the step accepts, e.g. `driver-license-us`, `passport-us` |
| `document.valid_states` | string\[] | US states / Canadian provinces the step accepts for state-issued documents |
| `face.face_front_photo_only` | boolean | Whether only a single front-facing selfie is required (vs. additional angles) |
#### FACE\_LIVENESS requirements
| Field | Type | Description |
| ---------------------- | ------ | ------------------------------------------------------------------ |
| `challenge_type` | string | The liveness challenge method to run, e.g. `FaceMovementChallenge` |
| `confidence_threshold` | number | Minimum liveness confidence score (0-100) required to pass |
### Error responses
| Status | Description |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Invalid request body, or the workflow contains a step type not supported by the Workflow Runner API (response includes `invalid_steps`), or the workflow is not `active` |
| `401` | Invalid or missing API key |
| `402` | Insufficient funds to run this workflow |
| `403` | The workflow belongs to a different organization |
| `404` | Organization or workflow not found |
| `429` | Too many requests |
```json 200 theme={null}
{
"session_id": "80e801af-991b-425c-96fc-f5e07d794253",
"expires_at": null,
"steps": [
{
"step_id": "ID_VERIFICATION",
"status": "PENDING",
"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",
"driver-license-ca",
"passport-us",
"passport-ca",
"national-id-us"
],
"valid_states": ["NY", "CA", "ON", "BC"]
},
"face": {
"face_front_photo_only": true
}
}
},
{
"step_id": "FACE_LIVENESS",
"status": "PENDING",
"requirements": {
"challenge_type": "FaceMovementChallenge",
"confidence_threshold": 70
}
}
],
"current_step": 0
}
```
```json 400 — Unsupported step theme={null}
{
"error": "Invalid workflow step",
"invalid_steps": ["pep-sanctions"]
}
```