> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Workflow API: Build KYC Flow

> Programmatically create a Didit verification workflow with ordered features. KYC, KYB, AML, and biometrics in one flow. Pay-per-call, no contracts.



Create Workflow API Prompt
        Copy prompt to clipboard



      
      

\<pre>

\`Create a simple Didit workflow through the Management API.

Endpoint:
POST https://verification.didit.me/v3/workflows/

Authentication:
Use the x-api-key header with my Didit API key.

Requirements:
\- Use the simple v3 API shape with features.
\- Send features in the exact order users should complete them.
\- Do not send workflow_graph, branches, actions, webhooks, or conditional logic.
\- Didit will convert the features array into a linear node-based workflow and add the final status step automatically.
\- Use uppercase feature values such as OCR, LIVENESS, FACE_MATCH, AML, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE_VERIFICATION, or PROOF_OF_ADDRESS.
\- Configure each feature with the fields from /management-api/workflows/feature-configs.
\- For an OCR feature, omit config.documents_allowed or send an empty object to allow every supported document type. Send config.documents_allowed only to restrict the allowed documents.
\- Put dependency features first. For example, put OCR before FACE_MATCH, NFC, DATABASE_VALIDATION, or user AML checks that depend on document data.
\- For a QUESTIONNAIRE feature, first create the questionnaire with POST /v3/questionnaires/ and use the returned questionnaire_id as config.questionnaire_uuid.
\- Store the workflow uuid returned by the response. Use it as workflow_id when creating sessions and as settings_uuid when updating this workflow.

Example KYC request body:
\{
"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"
}
]
}

Example questionnaire workflow body:
\{
"workflow_label": "Source of Funds",
"features": [
\{
  "feature": "QUESTIONNAIRE",
  "config": {
    "questionnaire_uuid": "11111111-2222-3333-4444-555555555555",
    "review_questionnaire_manually": true
  }
}
]
}

Build the API call, handle validation errors, and return the workflow uuid from the response.`

\</pre>



      
      

Paste into

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 `POST /v3/workflows/` endpoint creates **simple, linear** workflows only — a flat `features` list. For **branching, conditional routing, Document AI, and decline/decision nodes**, use the node **[graph format](#branching-&-node-based-workflows-graph)** documented below (it powers the visual builder in the console and the [Didit MCP](https://docs.didit.me/integration/mcp/overview.md) workflow tools).See [Workflow Feature Configs](https://docs.didit.me/management-api/workflows/feature-configs.md) for every `config` field accepted by each feature.## Basic KYC workflow```json theme={null}
{
  "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 workflowFirst create the questionnaire with `POST /v3/questionnaires/`. Then use the returned `questionnaire_id` as `questionnaire_uuid`.```json theme={null}
{
  "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 referenceEach `features[]` item has this shape:```json theme={null}
{
  "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](https://docs.didit.me/management-api/workflows/feature-configs.md).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 settingsYou 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.| Field | Type | Description |
| - | - | - |
| `is_white_label_enabled` | boolean | Enable white-label customization for sessions created with this workflow. Default `false`. |
| `is_desktop_allowed` | boolean | Allow the verification flow to run on desktop browsers. Default `false`. |
| `max_retry_attempts` | integer (0–10) | Maximum retry attempts allowed after a declined verification. `0` blocks the user after the first decline. Default `3`. |
| `retry_window_days` | integer (1–365) or `null` | Rolling window in days used to count retries (`null` = all-time limit). Default `7`. |
| `session_expiration_time` | integer (3600–2419200) | Seconds before an unfinished session expires. Minimum 1 hour, maximum 4 weeks. Default `604800` (7 days). |
| `response_attributes` | object or `null` | Limits the fields returned for each feature, for example `{"id_verifications": ["full_name", "document_number"], "face_matches": null}`. `null` or a missing key returns every field. An empty list returns only `status`, `warnings`, `node_id`, `is_nfc_skipped` and `skip_reason`, and other fields come back `null`. |```json theme={null}
{
  "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" }
  ]
}
```## Branching & node-based workflows (graph)A linear `features` list can't express "if X then Y." For **conditional branching** (decline on a status, route on an extracted field, gate a step on a match), a **Document AI** request step, or terminal **decline/decision** nodes, Didit workflows use a **node graph** — the same structure the console's visual builder produces.> [!NOTE]
>
> The simplest way to build a graph workflow is the **[Didit MCP](https://docs.didit.me/integration/mcp/overview.md)** — ask an agent in plain language ("after ID verification, if the profession is ≈ 'Software Engineer', add a proof-of-funds step") and it constructs, validates, and saves the graph for you. The structure below is what those tools (and the console) produce.### Graph shapeA graph is `{ start_node, nodes }`. `nodes` is a map of node id → node. Edges are implicit: each node points forward via `next` (unconditional) and/or `branches[].goto` (conditional).| Node type | Shape |
| - | - |
| `feature` | `{ "node_type": "feature", "feature": "OCR", "config": {…}, "next": "<id>", "branches": [] }` |
| `branch` | `{ "node_type": "branch", "branches": [ { "id", "logic": "and"\|"or", "rules": [<rule>], "goto": "<id>" } ], "next": "<fallback id>" }` |
| `status` (terminal) | `{ "node_type": "status", "session_status": "Approved"\|"Declined"\|"In Review"\|"Determine" }` |
| `action` | `{ "node_type": "action", "actions": [ { "type": "add_tag"\|"add_review"\|… } ], "next": "<id>" }` |
| `webhook` | `{ "node_type": "webhook", "config": { "url", "method" }, "branches": [], "next": "<id>" }` |`start_node` must be a feature node. Branches are evaluated in order, **first match wins**; an empty `rules: []` is the catch-all "else" (keep it last). `session_status: "Determine"` auto-decides from the combined feature outcomes.> [!WARNING]
>
> **Every branch node must have an explicit else branch** — a branch with `rules: []` that routes sessions matching none of the conditions. Don't rely on the branch node's `next` as the fallback: a bare `next` renders as an ambiguous edge in the builder and is easy to omit. When you send a branch node with a `next` and no else branch, the API **converts that `next` into an explicit else branch** for you (so `{ …, "branches": [<conditions>], "next": "liveness" }` is saved as `branches: [<conditions>, { "id": "else", "rules": [], "goto": "liveness" }]`). Build the else yourself to be explicit; the conversion is a safety net, not a substitute.### Branch rules & operatorsEach rule compares a **field** to a **value** with an **operator**:```json theme={null}
{ "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 }
```- **Fields** name a feature outcome (`kyc.status`, `aml.status`, `document_ai.status`, `face_match.score`, …) or an extracted value (`kyc.full_name`, `kyc.age`, `kyc.nationality`, `kyc.extra_fields.profession`, a Document-AI field `document_ai.<key>`, `expected_details.*`). A branch may only read a field whose feature has run on every path reaching it.
- **Operators:** `equals`, `not_equals`, `greater_than(_or_equals)`, `less_than(_or_equals)`, `contains`, `not_contains`, `in`, `not_in`, `is_empty`, `is_not_empty`, `regex`, and **`fuzzy_match`** (string fields only; requires a `score` 0–100 — a similarity threshold, e.g. profession ≥ 80% similar to "Software Engineer").### Branch on why NFC did not runAfter an `NFC` node, use `nfc.skip_reason` with `equals` or `in` to route sessions by why the chip read did not happen. The field has these seven stable values:- `USER_SKIPPED`
- `DOCUMENT_WITHOUT_CHIP`
- `CHIP_CERTIFICATE_UNAVAILABLE`
- `DEVICE_WITHOUT_NFC`
- `INTEGRATION_WITHOUT_NFC_ACCESS`
- `MRZ_KEY_UNAVAILABLE`
- `JPKI_UNAVAILABLE`See [NFC skip reasons](https://docs.didit.me/core-technology/nfc-verification/warnings-nfc-verification.md#skip-reasons) for what each value means. When NFC succeeds, `nfc.skip_reason` is `null`, so neither an `equals` nor an `in` rule for a skip reason matches.The field also resolves for **gate-skipped** NFC nodes. This includes cases where no NFC report or warning exists, and cases where `allow_nfc_skip` is `false` but the document or device gate prevents NFC from running. You can therefore route these sessions without relying on an `nfc_verifications[]` entry.> [!NOTE]
>
> Sessions stored before NFC capability became tri-state can have `has_device_nfc_support: false`. An older web session may therefore resolve to `DEVICE_WITHOUT_NFC` instead of `INTEGRATION_WITHOUT_NFC_ACCESS`.This graph uses `equals` for a user skip, `in` for gate or capability skips, and an explicit else for successful NFC. The branch comes after the `NFC` node, and every destination points forward to a terminal node:```json theme={null}
{
  "start_node": "ocr",
  "nodes": {
    "ocr": {
      "node_type": "feature",
      "feature": "OCR",
      "next": "nfc"
    },
    "nfc": {
      "node_type": "feature",
      "feature": "NFC",
      "config": { "allow_nfc_skip": false },
      "next": "route_nfc"
    },
    "route_nfc": {
      "node_type": "branch",
      "branches": [
        {
          "id": "user_skipped",
          "logic": "and",
          "rules": [
            { "field": "nfc.skip_reason", "operator": "equals", "value": "USER_SKIPPED" }
          ],
          "goto": "manual_review"
        },
        {
          "id": "nfc_unavailable",
          "logic": "and",
          "rules": [
            {
              "field": "nfc.skip_reason",
              "operator": "in",
              "value": [
                "DOCUMENT_WITHOUT_CHIP",
                "CHIP_CERTIFICATE_UNAVAILABLE",
                "DEVICE_WITHOUT_NFC",
                "INTEGRATION_WITHOUT_NFC_ACCESS",
                "MRZ_KEY_UNAVAILABLE",
                "JPKI_UNAVAILABLE"
              ]
            }
          ],
          "goto": "manual_review"
        },
        {
          "id": "else",
          "logic": "and",
          "rules": [],
          "goto": "approved"
        }
      ]
    },
    "manual_review": { "node_type": "status", "session_status": "In Review" },
    "approved": { "node_type": "status", "session_status": "Approved" }
  }
}
```To express “NFC was not performed for any known reason,” use `in` with **all seven** values. Keep an explicit else branch for successful NFC (`nfc.skip_reason: null`) and any future value that your graph does not yet recognize.### Document AI (e.g. proof of funds)A `DOCUMENT_AI` feature node requests one or more documents and extracts named fields:```json theme={null}
{
  "node_type": "feature",
  "feature": "DOCUMENT_AI",
  "label": "Proof of Funds",
  "config": {
    "document_ai_documents": [
      {
        "document_key": "proof_of_funds",
        "title": "Proof of Funds",
        "description": "Upload a recent bank statement.",
        "fields": [
          {
            "key": "account_holder",
            "name": "Account holder",
            "instruction": "The full name of the account holder as printed on the statement.",
            "type": "text",
            "required": true,
            "is_full_name": true
          },
          {
            "key": "closing_balance",
            "name": "Closing balance",
            "instruction": "The closing balance amount.",
            "type": "number",
            "required": true
          }
        ]
      }
    ],
    "document_ai_missing_required_fields_action": "REVIEW",
    "document_ai_name_mismatch_action": "REVIEW"
  },
  "next": "final_decision"
}
```Each configured field becomes a branchable value `document_ai.<key>`, and the step's outcome is `document_ai.status`.Set `"is_full_name": true` on the field that holds the document holder's full name. Its extracted value is compared against the verified identity's full name (the OCR/ID-verification name, or the session's expected details), and `document_ai_name_mismatch_action` decides what happens on a mismatch below `document_ai_name_match_score_threshold`. The flag is **optional** — a document may mark no field — and **at most one field per document** may set it. See [Workflow feature configs → Document AI](https://docs.didit.me/management-api/workflows/feature-configs.md#document-ai) for every Document AI config field.### Endpoints & draft lifecycleGraph editing is per-application and uses the console/management endpoints (user-Bearer + `read:workflows`/`write:workflows`). A graph can only be edited on a **draft** version, so the lifecycle is **create-draft → set graph → publish**:| Method | Path | Purpose |
| - | - | - |
| `GET` | `…/verification-settings/{settings_uuid}/workflow-graph/` | Current graph + `status`/`is_editable` |
| `POST` | `…/application/{app}/workflow-graph/validate/` (body `{ "graph": … }`) | Dry-run validation |
| `GET` | `…/application/{app}/workflow-graph/field-definitions/` | Branchable fields + valid operators |
| `POST` | `…/verification-settings/{settings_uuid}/create-draft/` | Editable draft from a published version |
| `PUT` | `…/verification-settings/{settings_uuid}/workflow-graph/` (body `{ "graph": … }`) | Save the graph |
| `PATCH` | `…/verification-settings/{settings_uuid}/` (body `{ "status": "published" }`) | Publish the draft |#### Validation warningsThe validate endpoint answers `{ "is_valid": true, "graph": …, "warnings": [] }`. A warning is **advisory**: the graph is valid, it saves and it publishes with warnings present. Each entry carries the branch node and arm it is about, so a builder can point at the exact condition:```json theme={null}
{
  "type": "branch_outcome_contradiction",
  "node_id": "after_ocr",
  "branch_id": "b1",
  "severity": "warning",
  "message": "Branch 1 only matches sessions where ID Verification Status is Approved or In Review, but every path from it ends in the session outcome \"Declined\". Check the condition or the outcome.",
  "params": { "branchNumber": 1, "field": "ID Verification Status", "allowed": "Approved or In Review", "outcome": "Declined" }
}
```| `type` | What it means |
| - | - |
| `branch_outcome_contradiction` | The arm's condition and the outcome every path from it reaches contradict each other - for example `kyc.status NOT EQUALS Declined` routed into a `Declined` outcome. The outcome may be several steps further down the path. |
| `branch_condition_unreachable` | The arm can never match, because every path reaching this branch already limits that status field to values the condition excludes. |
| `else_branch_unreachable` | The else arm can never run: the other arms already cover every value the field can hold here. |An invalid graph answers `400` with `errors` **and** a best-effort `warnings` list. Only `errors` block a save.### Worked example: route Software Engineers to proof of funds> After ID verification: if it was **declined**, decline the session; if the holder's **profession ≈ "Software Engineer"** (≥80% similar), request a **proof-of-funds** document; then make a final decision.```json theme={null}
{
  "start_node": "ocr_1",
  "nodes": {
    "ocr_1": { "node_type": "feature", "feature": "OCR", "label": "ID Verification", "next": "after_ocr" },
    "after_ocr": {
      "node_type": "branch",
      "label": "Route after ID verification",
      "branches": [
        { "id": "declined", "logic": "or", "rules": [ { "field": "kyc.status", "operator": "equals", "value": "Declined" } ], "goto": "decline" },
        { "id": "software_engineer", "logic": "and", "rules": [ { "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 } ], "goto": "proof_of_funds" },
        { "id": "else", "logic": "and", "rules": [], "goto": "final_decision" }
      ]
    },
    "proof_of_funds": {
      "node_type": "feature",
      "feature": "DOCUMENT_AI",
      "label": "Proof of Funds",
      "config": {
        "document_ai_documents": [
          { "document_key": "proof_of_funds", "title": "Proof of Funds", "description": "Upload a recent bank statement.",
            "fields": [
              { "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
              { "key": "closing_balance", "name": "Closing balance", "type": "number", "required": true }
            ] }
        ],
        "document_ai_missing_required_fields_action": "REVIEW"
      },
      "next": "final_decision"
    },
    "final_decision": { "node_type": "status", "session_status": "Determine", "label": "Final decision" },
    "decline": { "node_type": "status", "session_status": "Declined", "label": "Declined" }
  }
}
```The final node uses `session_status: "Determine"`, which **auto-decides** (approve / decline / in-review) from whatever features actually ran on the session — so both the proof-of-funds path and the else path resolve correctly without any branch reading `document_ai.status` (which doesn't exist on the path that skips Document AI). Remember: a branch may only read a field whose feature ran on *every* path reaching it.Send it as `{ "graph": <above> }` to the `…/workflow-graph/` endpoint (validate first). To build a **new** workflow from scratch use the MCP's `didit_workflow_set_graph`; to **modify an existing** workflow use `didit_workflow_edit_graph` (small ops, preserves the existing nodes and allow-lists). See the [Didit MCP](https://docs.didit.me/integration/mcp/tools.md).


## OpenAPI

````yaml openapi-25.json POST /v3/workflows/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/workflows/:
    post:
      tags:
        - Workflows
      summary: Create workflow
      description: >-
        Create a simple workflow. Send `features` in execution order (ordering
        rules apply); defaults to `published` v1. The body accepts ONLY the
        fields listed in `SimpleWorkflowRequest` — any other key (including
        `workflow_type`) is rejected with a 400. Not idempotent — each call
        creates a new workflow. Maximum 50 workflows per application.
      operationId: create_workflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleWorkflowRequest'
            examples:
              Simple KYC:
                summary: Linear ID, liveness, and face match workflow
                value:
                  workflow_label: Standard KYC
                  features:
                    - feature: OCR
                      config:
                        duplicated_user_action: review
                    - feature: LIVENESS
                      config:
                        face_liveness_method: passive
                    - feature: FACE_MATCH
                      config:
                        face_match_score_decline_threshold: 40
                        face_match_score_review_threshold: 60
              KYC + AML:
                summary: Run AML after ID verification
                value:
                  workflow_label: KYC with AML
                  features:
                    - feature: OCR
                    - feature: AML
                      config:
                        aml_score_review_threshold: 70
                        aml_score_approve_threshold: 30
              Questionnaire workflow:
                summary: Run a questionnaire created with POST /v3/questionnaires/
                value:
                  workflow_label: Source of Funds
                  features:
                    - feature: QUESTIONNAIRE
                      config:
                        questionnaire_uuid: 11111111-2222-3333-4444-555555555555
                        review_questionnaire_manually: true
      responses:
        '201':
          description: >-
            Workflow created. The response body is the FULL workflow
            configuration — the same raw `VerificationSettings` serialization
            returned by `GET /v3/workflows/{settings_uuid}/` (~190 fields: every
            feature toggle, threshold, action and the generated
            `workflow_graph`), not the compact list item. Store the `uuid` (also
            exposed as `workflow_id`) so you can reference it from later
            session-creation calls. Note: `features` is a `" + "`-joined string
            and prices are JSON numbers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDetail'
              examples:
                Created (abbreviated):
                  summary: Key fields of the full configuration object
                  value:
                    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/u/w9TkPOx8RWG3UAz5ZRQGVQ
                    workflow_graph:
                      start_node: ocr
                      nodes: ... one node per feature plus a final status node ...
                    max_retry_attempts: 3
                    retry_window_days: 7
                    session_expiration_time: 604800
                    version: 1
                    status: published
                    published_at: '2026-05-17T10:30:00Z'
                    created_at: '2026-05-17T10:30:00Z'
                    updated_at: '2026-05-17T10:30:00Z'
        '400':
          description: >-
            Validation error. Common causes: a top-level key outside the
            accepted whitelist (e.g. `workflow_type`), an unknown `feature`
            value, a feature placed before its dependency (e.g., `FACE_MATCH`
            before `OCR`), a passive feature (`AML`, `IP_ANALYSIS`,
            `DATABASE_VALIDATION`, `KYB_KEY_PEOPLE`) used as the first step, a
            `QUESTIONNAIRE` feature whose `config.questionnaire_uuid` does not
            exist for this application, a `SIGNATURE` feature that would go live
            with no document to sign, a `SIGNATURE` feature at `signature_level:
            "aes"` while Advanced (AES) is not available (`aes_not_available`,
            see `signature_availability` on the workflow), or an out-of-range
            threshold. Body is a DRF validation error object — keys are field
            names, values are arrays of human-readable messages.
          content:
            application/json:
              examples:
                Advanced (AES) not available:
                  value:
                    features:
                      signature_level:
                        - >-
                          Node 'signature': Advanced (AES) is not available yet
                          (aes_not_available).
                Signature step with no document:
                  value:
                    features:
                      non_field_errors:
                        - >-
                          Node 'signature': Add a document to sign, or let each
                          session bring its own.
                Missing feature:
                  value:
                    features:
                      - At least one feature is required.
                Unknown top-level field:
                  value:
                    workflow_type:
                      - >-
                        The v3 workflow API only accepts `workflow_label`,
                        `is_default`, `status`, `features`,
                        `is_white_label_enabled`, `is_desktop_allowed`,
                        `max_retry_attempts`, `retry_window_days`,
                        `session_expiration_time`, `face_liveness_max_attempts`,
                        `face_match_max_attempts`.
                Unknown feature:
                  value:
                    features:
                      - >-
                        Invalid feature 'FOO'. Allowed values: AGE_ESTIMATION,
                        AML, DATABASE_VALIDATION, EMAIL_VERIFICATION,
                        FACE_MATCH, IP_ANALYSIS, KYB_DOCUMENTS, KYB_KEY_PEOPLE,
                        KYB_REGISTRY, LIVENESS, NFC, OCR, PHONE_VERIFICATION,
                        PROOF_OF_ADDRESS, QUESTIONNAIRE.
                Ordering:
                  value:
                    features:
                      - 'Feature ''FACE_MATCH'' must appear after one of: OCR.'
                Questionnaire not found:
                  value:
                    features: >-
                      Questionnaire '11111111-2222-3333-4444-555555555555' was
                      not found for this application. Create the questionnaire
                      first, then use its questionnaire_id.
        '403':
          description: >-
            The API key is missing, malformed, expired, or scoped to a different
            application. Refresh via the [Auth API](/auth-api/get-credentials)
            and retry.
          content:
            application/json:
              examples:
                Invalid token:
                  value:
                    detail: You do not have permission to perform this action.
        '415':
          description: >-
            Unsupported media type. Set `Content-Type: application/json` and
            send a JSON body.
        '429':
          description: Rate limit exceeded. Retry with exponential backoff.
        '500':
          description: Unexpected server error while creating the workflow. Safe to retry.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            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}}
                ]
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.workflows.create(
                workflow_label="Standard KYC",
                features=[{
                    "feature": "OCR",
                    "config": {"duplicated_user_action": "review"},
                }, {
                    "feature": "LIVENESS",
                    "config": {"face_liveness_method": "passive"},
                }, {
                    "feature": "FACE_MATCH",
                    "config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60},
                }],
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.workflows.create({
              workflow_label: "Standard KYC",
              features: [{
                feature: "OCR",
                config: { duplicated_user_action: "review" },
              }, {
                feature: "LIVENESS",
                config: { face_liveness_method: "passive" },
              }, {
                feature: "FACE_MATCH",
                config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },
              }],
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{\n\tWorkflowLabel: didit.String(\"Standard KYC\"),\n\tFeatures: []didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t\tConfig:  didit.Some(map[string]any{\"duplicated_user_action\": \"review\"}),\n\t}, {\n\t\tFeature: \"LIVENESS\",\n\t\tConfig:  didit.Some(map[string]any{\"face_liveness_method\": \"passive\"}),\n\t}, {\n\t\tFeature: \"FACE_MATCH\",\n\t\tConfig:  didit.Some(map[string]any{\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.util.List;

            import java.util.Map;

            import me.didit.Didit;

            import me.didit.types.SimpleWorkflowFeature;

            import me.didit.types.SimpleWorkflowRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.workflows().create(SimpleWorkflowRequest.builder()
                    .workflowLabel("Standard KYC")
                    .features(List.of(
                            SimpleWorkflowFeature.builder()
                                    .feature(SimpleWorkflowFeature.Feature.of("OCR"))
                                    .config(Map.of("duplicated_user_action", "review"))
                                    .build(),
                            SimpleWorkflowFeature.builder()
                                    .feature(SimpleWorkflowFeature.Feature.of("LIVENESS"))
                                    .config(Map.of("face_liveness_method", "passive"))
                                    .build(),
                            SimpleWorkflowFeature.builder()
                                    .feature(SimpleWorkflowFeature.Feature.of("FACE_MATCH"))
                                    .config(Map.of("face_match_score_decline_threshold", 40, "face_match_score_review_threshold", 60))
                                    .build()))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->workflows->create([
                'workflow_label' => 'Standard KYC',
                'features' => [[
                    'feature' => 'OCR',
                    'config' => ['duplicated_user_action' => 'review'],
                ], [
                    'feature' => 'LIVENESS',
                    'config' => ['face_liveness_method' => 'passive'],
                ], [
                    'feature' => 'FACE_MATCH',
                    'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60],
                ]],
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.workflows.create(
              workflow_label: "Standard KYC",
              features: [{
                feature: "OCR",
                config: { duplicated_user_action: "review" },
              }, {
                feature: "LIVENESS",
                config: { face_liveness_method: "passive" },
              }, {
                feature: "FACE_MATCH",
                config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },
              }]
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Collections.Generic;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.Workflows.CreateAsync(new
            SimpleWorkflowRequest

            {
                WorkflowLabel = "Standard KYC",
                Features = new SimpleWorkflowFeature[]
                {
                    new()
                    {
                        Feature = "OCR",
                        Config = new Dictionary<string, object> { ["duplicated_user_action"] = "review" },
                    },
                    new()
                    {
                        Feature = "LIVENESS",
                        Config = new Dictionary<string, object> { ["face_liveness_method"] = "passive" },
                    },
                    new()
                    {
                        Feature = "FACE_MATCH",
                        Config = new Dictionary<string, object> { ["face_match_score_decline_threshold"] = 40, ["face_match_score_review_threshold"] = 60 },
                    },
                },
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    SimpleWorkflowRequest:
      type: object
      description: >-
        Create a simple linear workflow. The API converts this feature list into
        a node-based workflow graph internally. STRICT field whitelist: any key
        not listed here (including `workflow_type`) is rejected with a 400.
      required:
        - features
      properties:
        workflow_label:
          type: string
          maxLength: 50
          default: ID Verification
          description: >-
            Display name for the workflow (max 50 characters). Defaults to `"ID
            Verification"` when omitted — always set it so workflows stay
            distinguishable.
          example: Standard KYC
        is_default:
          type: boolean
          description: Set this workflow as the default for new sessions.
        status:
          type: string
          enum:
            - draft
            - published
          description: >-
            Omit this field to create a published workflow ready for sessions.
            Use `draft` only when you want to save without publishing.
        features:
          type: array
          minItems: 1
          description: >-
            Verification features in execution order. The API links each item to
            the next one and adds one final status node automatically.
          items:
            $ref: '#/components/schemas/SimpleWorkflowFeature'
        is_white_label_enabled:
          type: boolean
          description: >-
            Enable white-label customization for sessions created with this
            workflow.
          default: false
        is_desktop_allowed:
          type: boolean
          description: Allow the verification flow to run on desktop browsers.
          default: false
        max_retry_attempts:
          type: integer
          minimum: 0
          maximum: 10
          default: 3
          description: >-
            Maximum retry attempts allowed after a declined verification. `0`
            blocks the user after the first decline.
        retry_window_days:
          type: integer
          minimum: 1
          maximum: 365
          nullable: true
          default: 7
          description: >-
            Rolling window in days used to count retries. `null` enforces an
            all-time limit.
        face_liveness_max_attempts:
          type: integer
          minimum: 1
          maximum: 3
          default: 3
          description: >-
            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.
        face_match_max_attempts:
          type: integer
          minimum: 1
          maximum: 3
          default: 3
          description: >-
            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.
        session_expiration_time:
          type: integer
          minimum: 3600
          maximum: 2419200
          default: 604800
          description: >-
            Seconds before an unfinished session expires. Minimum 1 hour (3600),
            maximum 4 weeks (2419200).
    WorkflowDetail:
      type: object
      description: >-
        The fields below are typed; the object also carries every other column
        of the workflow configuration (feature toggles, thresholds, warning
        actions, allowed documents, callbacks) as additional properties. Fields
        that do not apply to the `workflow_type` are `null`.
      properties:
        uuid:
          type: string
          format: uuid
          description: >-
            Per-version identifier (`settings_uuid`). Every version of a
            workflow has its own.
        workflow_id:
          type: string
          format: uuid
          description: >-
            Stable identifier shared by every version of the workflow. Sessions
            created with it use the latest published version.
        workflow_label:
          type: string
          description: Display name of the workflow.
        workflow_type:
          type: string
          nullable: true
          enum:
            - kyc
            - kyb
            - adaptive_age_verification
            - biometric_authentication
            - address_verification
            - questionnaire_verification
            - email_verification
            - phone_verification
            - null
          description: >-
            Workflow template. `null` for graph workflows created without a
            template.
        is_default:
          type: boolean
          description: Whether this is the application's default workflow.
        is_archived:
          type: boolean
          description: Archived workflows cannot start new sessions.
        version:
          type: integer
          description: Version number within the workflow.
        status:
          type: string
          enum:
            - draft
            - published
          description: >-
            Draft versions are editable; published versions are immutable and
            used for new sessions.
        published_at:
          type: string
          format: date-time
          nullable: true
          description: When this version was published. `null` for drafts.
        is_simple_workflow:
          type: boolean
          description: '`true` when the workflow has no custom `workflow_graph`.'
        is_editable:
          type: boolean
          description: '`true` only for `draft` versions.'
        workflow_url:
          type: string
          format: uri
          description: Public URL that starts a session with this workflow.
        workflow_graph:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Graph structure of the workflow (nodes and edges). `null` for simple
            workflows.
        features:
          type: string
          description: >-
            Enabled features joined with `" + "`, for example `"OCR +
            LIVENESS"`.
        total_price:
          type: number
          nullable: true
          description: Price per session; for graph workflows the most expensive path.
        min_price:
          type: number
          nullable: true
          description: Price of the cheapest path through the workflow.
        max_price:
          type: number
          nullable: true
          description: Price of the most expensive path through the workflow.
        special_add_on_prices:
          type: object
          nullable: true
          additionalProperties: true
          description: Organization-specific add-on prices, or `null` when none are set.
        max_retry_attempts:
          type: integer
          description: Retries allowed after a declined verification.
        retry_window_days:
          type: integer
          nullable: true
          description: Days during which the retries are allowed.
        session_expiration_time:
          type: integer
          description: Seconds before an unfinished session expires.
        questionnaire:
          type: object
          nullable: true
          additionalProperties: true
          description: The questionnaire attached to the workflow, or `null`.
        kyb_role_settings:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Per-role verification settings for KYB key people.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        signature_availability:
          type: object
          description: >-
            Which E-signature levels can sign right now. Check it before you set
            `signature_level`. Returned on `kyc`, `kyb` and graph workflows.
          properties:
            simple:
              type: boolean
              description: Simple is always available.
            aes:
              type: boolean
              description: >-
                Whether Advanced (AES) can sign now. While it is `false`, saving
                a new step at `signature_level: "aes"` is refused with
                `aes_not_available`.
            qes:
              type: boolean
              description: >-
                Whether Qualified (QES) can sign now. It is `false` until a
                qualified provider is connected.
        is_bank_verification_enabled:
          type: boolean
          description: >-
            Whether a simple KYC or KYB workflow runs Bank verification. It runs
            after the contact steps (and Location verification) and before
            database validation, AML and IP analysis. Bank verification is not
            generally available yet: turning it on is refused wherever it is not
            enabled.
        bank_verification_config:
          type: object
          additionalProperties: true
          description: >-
            Bank verification settings of a simple workflow, with the same keys
            a `BANK_VERIFICATION` node takes (for example `bank_countries` and
            `bank_method_order`). Unknown keys are dropped. Every key is
            optional and an absent key keeps its default, so `{}` means all
            defaults. See [Bank verification
            settings](/management-api/workflows/feature-configs#bank-verification).
          example: {}
        is_geolocation_enabled:
          type: boolean
          description: >-
            Whether a simple KYC workflow runs Location verification. It runs
            after the contact steps and before Bank verification and database
            validation. Business (KYB) workflows cannot run it.
        geolocation_config:
          type: object
          additionalProperties: true
          description: >-
            Location verification settings of a simple workflow, with the same
            keys a `GEOLOCATION` node takes (for example
            `is_geolocation_geofencing_enabled` and `geolocation_max_attempts`).
            Unknown keys are dropped. Every key is optional and an absent key
            keeps its default, so `{}` means all defaults.
          example: {}
      additionalProperties: true
    SimpleWorkflowFeature:
      type: object
      required:
        - feature
      properties:
        feature:
          type: string
          description: Feature to run. Use the uppercase values shown here.
          enum:
            - OCR
            - NFC
            - LIVENESS
            - FACE_MATCH
            - PROOF_OF_ADDRESS
            - QUESTIONNAIRE
            - DOCUMENT_AI
            - PHONE_VERIFICATION
            - EMAIL_VERIFICATION
            - DATABASE_VALIDATION
            - AML
            - IP_ANALYSIS
            - AGE_ESTIMATION
            - KYB_REGISTRY
            - KYB_DOCUMENTS
            - KYB_KEY_PEOPLE
            - SIGNATURE
        config:
          type: object
          description: >-
            Feature-specific settings. For `QUESTIONNAIRE`, include
            `questionnaire_uuid` with the `questionnaire_id` returned by the
            questionnaire create endpoint. For `SIGNATURE`, a workflow that goes
            live needs a document to sign: set `signature_documents_source` to
            `session` or `both` so each session can bring its own, or send
            `status: "draft"` and add the documents before you publish.
            `signature_level: "aes"` is refused with `aes_not_available` while
            `signature_availability.aes` is `false` on the workflow. For `OCR`,
            `methods` selects which ID Verification methods each country may use
            (document capture, non-doc lookup against a government or other
            authoritative source, and digital identity wallets); omit it and
            every country is document capture only. For `SIGNATURE`, see
            [E-signature
            settings](/management-api/workflows/feature-configs#e-signature):
            `signature_level` accepts `simple` (the default, no ID verification,
            email or phone needed) and `aes` for now, and workflow documents and
            their fields are managed in the console, so through the API send
            documents and fields per session with `signature_documents_source:
            "session"`.
          additionalProperties: true
        label:
          type: string
          description: Optional internal label for this workflow node.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your application's API key, from Developers -> API keys in the Business
        Console. The primary key has full access. A named key can be scoped:
        none, read or write per resource, limited to some workflows or to
        approved sessions, to a list of IP addresses, and to an expiry date. 401
        means the key is wrong, revoked or expired; 403 means no key was sent,
        the key has no access to this resource or action, or the request came
        from an address outside its IP list; 404 on a session route means the
        session is outside the key's workflows or statuses. A key without media
        access receives image, video and PDF URLs as null, and a key without
        sessions write receives session links and tokens as null. See
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.