Skip to main content
POST
/
v1
/
workflows
Create Workflow
curl --request POST \
  --url https://api.deepidv.com/v1/workflows
{
  "workflow": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Full KYC Workflow",
    "status": "active",
    "organization_id": "da760e2f-2f7b-4f5d-b394-766ce9c4fad8",
    "created_at": "2026-03-31T14:00:00.000Z",
    "updated_at": "2026-03-31T14:00:00.000Z",
    "steps": [
      {
        "id": "id-verification",
        "config": {
          "age_restriction_settings": {
            "age_restriction_mode": "slider",
            "country_category_minimum_age": null,
            "minimum_age": { "lower": 21, "upper": 51 }
          },
          "expiry_date_settings": { "expiry_date": 5 },
          "face_scan_settings": { "face_front_photo_only": false },
          "id_scan_face_settings": { "require_front_only": false },
          "id_scan_settings": {
            "require_secondary_id": false,
            "require_tertiary_id": false
          },
          "valid_id_types_settings": {
            "valid_id_types": {
              "driver_license_ca": true,
              "driver_license_us": true,
              "passport_ca": true,
              "passport_us": true
            }
          },
          "valid_states_settings": {
            "valid_states": { "AL": true, "AK": true, "AZ": true, "...": "all US + CA" }
          }
        }
      },
      {
        "id": "face-liveness",
        "config": {
          "face_liveness_confidence_settings": { "confidence_threshold": 85 },
          "face_liveness_settings": { "preferred_liveness_method": "FaceMovementChallenge" }
        }
      },
      {
        "id": "age-estimation",
        "config": {
          "age_restriction_settings": {
            "age_restriction_mode": "slider",
            "country_category_minimum_age": null,
            "minimum_age": { "lower": 18, "upper": 100 }
          }
        }
      },
      { "id": "pep-sanctions", "config": {} },
      { "id": "adverse-media", "config": {} }
    ]
  }
}

POST /v1/workflows
Creates a new workflow for your organization. Workflows define the ordered sequence of verification steps that applicants must complete. Currently supported steps: ID_VERIFICATION, FACE_LIVENESS, AGE_ESTIMATION, PEP_SANCTIONS, ADVERSE_MEDIA.

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key

​
Body parameters

ParameterTypeRequiredDescription
namestringYesWorkflow name (1–255 characters)
stepsarrayYesOrdered list of verification steps (1–10, no duplicates)
steps[].idstringYesStep identifier (see Available Steps)
steps[].configobjectNoStep-specific configuration overrides (see Step Configuration)

​
Available Steps

Step IDDescription
ID_VERIFICATIONGovernment ID scanning and validation
FACE_LIVENESSActive anti-spoofing liveness detection
AGE_ESTIMATIONBiometric age estimation
PEP_SANCTIONSPolitically exposed persons & sanctions screening
ADVERSE_MEDIANegative press and media mention detection

​
Step Configuration

Each step accepts optional configuration. If omitted, sensible defaults are applied.

​
ID_VERIFICATION config

FieldTypeDefaultDescription
minimum_ageinteger18Minimum accepted age
maximum_ageinteger51Maximum accepted age
expiry_date_yearsinteger2Maximum years until ID expiry is rejected
require_secondary_idbooleanfalseRequire a second form of ID
require_tertiary_idbooleanfalseRequire a third form of ID
face_front_photo_onlybooleanfalseOnly capture front-facing photo
require_front_onlybooleanfalseOnly scan front of ID

​
FACE_LIVENESS config

FieldTypeDefaultDescription
confidence_thresholdinteger70Liveness confidence threshold (1–100)

​
AGE_ESTIMATION config

FieldTypeDefaultDescription
minimum_ageinteger18Minimum age requirement (1–100)

​
PEP_SANCTIONS / ADVERSE_MEDIA

No configuration options. These steps use default settings.

​
Example request

curl -X POST "https://api.deepidv.com/v1/workflows" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Full KYC Workflow",
    "steps": [
      {
        "id": "ID_VERIFICATION",
        "config": {
          "minimum_age": 21,
          "expiry_date_years": 5
        }
      },
      {
        "id": "FACE_LIVENESS",
        "config": {
          "confidence_threshold": 85
        }
      },
      { "id": "AGE_ESTIMATION" },
      { "id": "PEP_SANCTIONS" },
      { "id": "ADVERSE_MEDIA" }
    ]
  }'

​
Response

​
201 — Created

Returns the full workflow record. The response uses the same format as Retrieve Workflow.
FieldTypeDescription
workflowobjectThe created workflow record
workflow.idstringUnique workflow identifier
workflow.namestringWorkflow name
workflow.statusstringAlways active for newly created workflows
workflow.organization_idstringYour organization ID
workflow.created_atstringISO 8601 creation timestamp
workflow.updated_atstringISO 8601 last-updated timestamp
workflow.stepsarrayOrdered list of steps with full resolved configuration

​
Error responses

StatusDescription
400 Bad RequestInvalid request body (missing name, invalid step ID, invalid config, duplicate steps)
401 UnauthorizedMissing or invalid API key
403 ForbiddenSandbox API keys cannot create workflows
429 Too Many RequestsRate limit exceeded
{
  "workflow": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Full KYC Workflow",
    "status": "active",
    "organization_id": "da760e2f-2f7b-4f5d-b394-766ce9c4fad8",
    "created_at": "2026-03-31T14:00:00.000Z",
    "updated_at": "2026-03-31T14:00:00.000Z",
    "steps": [
      {
        "id": "id-verification",
        "config": {
          "age_restriction_settings": {
            "age_restriction_mode": "slider",
            "country_category_minimum_age": null,
            "minimum_age": { "lower": 21, "upper": 51 }
          },
          "expiry_date_settings": { "expiry_date": 5 },
          "face_scan_settings": { "face_front_photo_only": false },
          "id_scan_face_settings": { "require_front_only": false },
          "id_scan_settings": {
            "require_secondary_id": false,
            "require_tertiary_id": false
          },
          "valid_id_types_settings": {
            "valid_id_types": {
              "driver_license_ca": true,
              "driver_license_us": true,
              "passport_ca": true,
              "passport_us": true
            }
          },
          "valid_states_settings": {
            "valid_states": { "AL": true, "AK": true, "AZ": true, "...": "all US + CA" }
          }
        }
      },
      {
        "id": "face-liveness",
        "config": {
          "face_liveness_confidence_settings": { "confidence_threshold": 85 },
          "face_liveness_settings": { "preferred_liveness_method": "FaceMovementChallenge" }
        }
      },
      {
        "id": "age-estimation",
        "config": {
          "age_restriction_settings": {
            "age_restriction_mode": "slider",
            "country_category_minimum_age": null,
            "minimum_age": { "lower": 18, "upper": 100 }
          }
        }
      },
      { "id": "pep-sanctions", "config": {} },
      { "id": "adverse-media", "config": {} }
    ]
  }
}