Draw any flow.
Ship it in minutes.

# Didit Workflow Orchestrator — integrate in 5 minutes

You are wiring the Didit Workflow Orchestrator into <my_stack>. Follow
these steps exactly. Every URL, header, and enum value below is
canonical — do not paraphrase or "improve" them.

Workflows are versioned JSON documents that string together any subset
of Didit's 25+ verification modules:
  - Feature nodes (Optical Character Recognition (OCR), LIVENESS, FACE_MATCH, Anti-Money Laundering (AML), Near Field Communication (NFC), IP, QUESTIONNAIRE,
    PROOF_OF_ADDRESS, DATABASE_VALIDATION, AGE_ESTIMATION, EMAIL_VERIFICATION,
    PHONE_VERIFICATION)
  - Branch nodes (route by country, risk score, document type, age, ...)
  - Action nodes (add tag, set metadata, route to manual review)
  - Status nodes (APPROVED, DECLINED, IN_REVIEW)

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/

## 2. Two ways to build a workflow — pick one

### Path A — Visual canvas (recommended for humans)
1. Open https://docs.didit.me/console/workflows.
2. Pick Simple Mode for a template-based build (Know Your Customer (KYC), Age Verification,
   Biometric Auth, Address, Questionnaire) or Advanced Mode for the
   node-based graph builder.
3. Drag feature nodes onto the canvas. Connect handles with the smart-
   connect cursor. Drop branch nodes between features to route on data.
4. Click Publish. The published workflow's UUID is your workflow_id.

### Path B — Management API (recommended for AI agents)
Programmatically create a linear workflow with the simple v3 features
array — Didit converts it into a node-based graph internally.

POST https://verification.didit.me/v3/workflows/
Headers:
  x-api-key: <your-api-key>
  Content-Type: application/json
Body:
  {
    "workflow_label": "Standard KYC",
    "features": [
      {
        "feature": "OCR",
        "config": {
          "documents_allowed": {},
          "duplicated_user_action": "REVIEW"
        }
      },
      { "feature": "LIVENESS", "config": { "face_liveness_method": "PASSIVE" } },
      { "feature": "FACE_MATCH" },
      { "feature": "AML" }
    ]
  }

Hard rules for POST /v3/workflows/:
  - features[].feature values are UPPERCASE strict enum:
    OCR, LIVENESS, FACE_MATCH, AML, NFC, IP, QUESTIONNAIRE,
    PROOF_OF_ADDRESS, DATABASE_VALIDATION, AGE_ESTIMATION,
    EMAIL_VERIFICATION, PHONE_VERIFICATION
  - Put dependency features first. OCR before FACE_MATCH, NFC,
    DATABASE_VALIDATION, or user-AML checks that depend on document
    data. LIVENESS before FACE_MATCH.
  - For QUESTIONNAIRE features, create the questionnaire first via
    POST /v3/questionnaires/ and use the returned questionnaire_id as
    config.questionnaire_uuid.
  - The endpoint supports linear workflows only. To add branches,
    actions, webhooks, or conditional routing, edit the published
    workflow in the canvas.
  - Save the returned workflow uuid — that is your workflow_id for
    creating sessions, and your settings_uuid for future updates.

Reference for every config field per feature:
  https://docs.didit.me/management-api/workflows/feature-configs

## 3. Use the workflow in a session
POST https://verification.didit.me/v3/session/
Headers:
  x-api-key: <your-api-key>
  Content-Type: application/json
Body:
  {
    "workflow_id": "<uuid from step 2>",
    "vendor_data": "user-42"
  }

Response includes a session_url. Redirect the user there. The hosted
Didit UI handles capture UX, mobile handoff, accessibility, retries,
and webhook delivery on completion.

## 4. Webhooks
Register one webhook destination per workspace:

POST https://verification.didit.me/v3/webhook/destinations/
Body: { "url": "https://yourapp.com/didit/webhooks",
        "events": ["session.verified", "session.review_started",
                   "session.declined", "session.expired"] }

Every delivery carries an X-Signature-V2 Hash-based Message Authentication
Code (HMAC) header.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Verify before trusting the payload:

  signature = hmac_sha256(secret, raw_body).hex()
  if signature != request.headers["X-Signature-V2"]:
      return 401

Retries use exponential backoff over 24 hours. The Console shows every
delivery, retry, and signature verification result.

## 5. Workflow versioning
Workflows support draft / publish versioning. Drafts are fully editable.
Publishing creates an immutable version that new sessions will use.
Sessions always reference the specific version they were created with,
so behaviour stays consistent even after you publish updates. Previous
versions are preserved and inspectable via the Management API.

## 6. Multi-app management
Each workspace can host multiple applications — typically Development,
Staging, Production. Each application carries its own API key, its own
workflows, and its own webhook destinations. Promote a published
workflow from Staging to Production by re-publishing in the target app
or by exporting and re-importing the workflow JSON.

## 7. A/B testing
Split traffic across two published workflow variants from inside the
canvas. Configure a percentage split, route by user cohort, ramp a new
module to 5% before going to 100%. Conversion metrics surface on the
workflow analytics view at https://docs.didit.me/console/analytics.

## 8. Hard rules — do not change
- Base URL stays  https://verification.didit.me  (NOT apx.didit.me).
- Auth header stays  x-api-key  (lowercase, hyphenated).
- Webhook signature header stays  X-Signature-V2  (NOT X-Signature).
- Feature enum is UPPERCASE strict — OCR, LIVENESS, FACE_MATCH, AML,
  NFC, IP, QUESTIONNAIRE, PROOF_OF_ADDRESS, DATABASE_VALIDATION,
  AGE_ESTIMATION, EMAIL_VERIFICATION, PHONE_VERIFICATION.
- Session status casing stays  "Approved" / "Declined" / "In Review" /
  "Expired" / "Not Finished"  (mixed case on session statuses,
  UPPERCASE_SNAKE on transaction and case statuses).

## 9. Pricing reference
The Workflow Orchestrator itself is FREE on every plan — no per-workflow
fee, no per-seat fee, unlimited workflows. You pay only for the modules
that run inside the workflow at the published per-success rates on
https://didit.me/pricing.

500 free verifications every month, forever, on every account.

## 10. Verify your integration
1. Create a sandbox API key at https://business.didit.me.
2. POST /v3/workflows/ with the Standard KYC body above. Save the uuid.
3. POST /v3/session/ with that workflow_id. Open the session_url in a
   browser and complete the flow with the sandbox test fixtures.
4. Confirm the session.verified webhook fires and X-Signature-V2 verifies.
5. Open the workflow in the canvas — verify the linear feature array
   was converted into the expected node graph.

Done. The Workflow Orchestrator is live. Reach out to support@didit.me
with the workspace id if you hit a wall.