Skip to main content
POST
/
v3
/
workflows
cURL
curl -X POST 'https://verification.didit.me/v3/workflows/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow_label": "Standard KYC",
    "features": [
      {"feature": "OCR"},
      {"feature": "LIVENESS", "config": {"face_liveness_method": "passive"}},
      {"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}}
    ]
  }'
{
  "uuid": "c3d4e5f6-7890-12cd-ef34-333333333333",
  "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333",
  "workflow_label": "Standard KYC",
  "workflow_type": null,
  "is_default": false,
  "is_archived": false,
  "total_price": "0.15",
  "min_price": "0.15",
  "max_price": "0.15",
  "features": [
    "OCR",
    "LIVENESS",
    "FACE_MATCH"
  ],
  "is_simple_workflow": false,
  "is_editable": false,
  "workflow_url": "https://verify.didit.me/session/c3d4",
  "max_retry_attempts": 3,
  "retry_window_days": 7,
  "session_expiration_time": 1440,
  "version": 1,
  "status": "published",
  "has_draft": false,
  "updated_at": "2026-05-17T10:30:00Z"
}
Use this endpoint to create workflows through the API without building workflow graph nodes yourself. Send a features array in the order users should complete the checks. Didit converts it into a node-based workflow internally and adds the final status step automatically. This endpoint supports simple linear workflows only. It does not support branching conditions, action nodes, or webhook nodes. See Workflow Feature Configs for every config field accepted by each feature.

​
Basic KYC workflow

{
  "workflow_label": "Standard KYC",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "documents_allowed": {
          "USA": {
            "DL": {
              "enabled": 1,
              "sides": 2
            }
          }
        },
        "duplicated_user_action": "REVIEW"
      }
    },
    {
      "feature": "LIVENESS",
      "config": {
        "face_liveness_method": "PASSIVE"
      }
    },
    {
      "feature": "FACE_MATCH"
    }
  ]
}

​
Questionnaire workflow

First create the questionnaire with POST /v3/questionnaires/. Then use the returned questionnaire_id as questionnaire_uuid. 
{
  "workflow_label": "Source of Funds",
  "features": [
    {
      "feature": "QUESTIONNAIRE",
      "config": {
        "questionnaire_uuid": "11111111-2222-3333-4444-555555555555",
        "review_questionnaire_manually": true
      }
    }
  ]
}
Feature order matters. For example, put OCR before FACE_MATCH, NFC, DATABASE_VALIDATION, or user AML checks that depend on document data.

​
Feature config reference

Each features[] item has this shape: 
{
  "feature": "OCR",
  "label": "ID Verification",
  "config": {}
}
The exact config object depends on the feature. Review the full field list, defaults, required settings, value ranges, and examples in Workflow Feature Configs. For OCR, omit config.documents_allowed, send null, or send {} to allow every supported document type. Include it only when you want to restrict the workflow to specific countries or document types. For QUESTIONNAIRE, config.questionnaire_uuid is required.

​
Optional workflow settings

You can include any of these top-level fields when creating a workflow to control session behavior. They are all optional and fall back to the workflow defaults when omitted.
FieldTypeDescription
is_white_label_enabledbooleanEnable white-label customization for sessions created with this workflow. Default false.
is_desktop_allowedbooleanAllow the verification flow to run on desktop browsers. Default false.
max_retry_attemptsinteger (0–10)Maximum retry attempts allowed after a declined verification. 0 blocks the user after the first decline. Default 3.
retry_window_daysinteger (1–365) or nullRolling window in days used to count retries (null = all-time limit). Default 7.
session_expiration_timeinteger (3600–2419200)Seconds before an unfinished session expires. Minimum 1 hour, maximum 4 weeks. Default 604800 (7 days).
{
  "workflow_label": "Standard KYC",
  "is_white_label_enabled": true,
  "is_desktop_allowed": true,
  "max_retry_attempts": 5,
  "retry_window_days": 14,
  "session_expiration_time": 86400,
  "features": [
    { "feature": "OCR" },
    { "feature": "LIVENESS" },
    { "feature": "FACE_MATCH" }
  ]
}

Authorizations

​
x-api-key
string
header
required

Body

application/json

Create a simple linear workflow. The API converts this feature list into a node-based workflow graph internally.

​
workflow_label
string
required

Display name for the workflow.

Example:

"Standard KYC"

​
features
object[]
required

Verification features in execution order. The API links each item to the next one and adds one final status node automatically.

Minimum array length: 1
​
is_default
boolean

Set this workflow as the default for new sessions.

​
status
enum<string>

Omit this field to create a published workflow ready for sessions. Use draft only when you want to save without publishing.

Available options:
draft,
published
​
is_white_label_enabled
boolean
default:false

Enable white-label customization for sessions created with this workflow.

​
is_desktop_allowed
boolean
default:false

Allow the verification flow to run on desktop browsers.

​
max_retry_attempts
integer
default:3

Maximum retry attempts allowed after a declined verification. 0 blocks the user after the first decline.

Required range: 0 <= x <= 10
​
retry_window_days
integer | null
default:7

Rolling window in days used to count retries. null enforces an all-time limit.

Required range: 1 <= x <= 365
​
face_liveness_max_attempts
integer
default:3

Maximum liveness submissions per session. Default 3: one initial attempt plus two retries. This value is also copied into generated liveness and age-estimation workflow nodes unless the feature-level config overrides it.

Required range: 1 <= x <= 3
​
face_match_max_attempts
integer
default:3

Maximum face-match submissions per session. Default 3: one initial attempt plus two retries. This value is also copied into generated face-match workflow nodes unless the feature-level config overrides it.

Required range: 1 <= x <= 3
​
session_expiration_time
integer
default:604800

Seconds before an unfinished session expires. Minimum 1 hour (3600), maximum 4 weeks (2419200).

Required range: 3600 <= x <= 2419200

Response

Workflow created. The response body is the full workflow record — store the uuid (also exposed as workflow_id) so you can reference it from later session-creation calls.

A workflow in the list view.

​
uuid
string<uuid>

Workflow UUID. Use as workflow_id when creating sessions.

​
workflow_label
string

Display name for the workflow

​
workflow_type
string | null

Base type: kyc, adaptive_age_verification, biometric_authentication, etc.

​
is_default
boolean

Whether this is the default workflow for new sessions

​
is_archived
boolean
​
total_price
string

Total price per verification in USD

​
min_price
string
​
max_price
string
​
features
string[]

Enabled features (e.g., OCR, LIVENESS, FACE_MATCH, AML)

​
is_simple_workflow
boolean

True if not graph-based

​
is_editable
boolean

True if no sessions have used this workflow

​
workflow_url
string
​
max_retry_attempts
integer
​
retry_window_days
integer
​
face_liveness_max_attempts
integer

Maximum liveness submissions per session. Default 3: one initial attempt plus two retries.

Required range: 1 <= x <= 3
​
face_match_max_attempts
integer

Maximum face-match submissions per session. Default 3: one initial attempt plus two retries.

Required range: 1 <= x <= 3
​
special_add_on_prices
object