Onboard a worker. Block re-applying bad actors.

You are integrating Didit into a gig marketplace to onboard drivers, couriers, freelancers, or creators. ONE Didit session, five checks:

  Verify the worker's identity (KYC) — ID document, liveness, face match, device + IP, AML against 1,300+ sanctions / Politically Exposed Person (PEP) / adverse-media lists — plus Face Search 1:N against your private worker index to block previously-banned workers re-applying under a new name. Add an OPTIONAL licence-registry cross-check when you onboard drivers.

Bundle pricing (verified live, 2026-05-17):
  - Full KYC bundle: $0.33 per worker (ID + Liveness + Face Match + Device & IP)
  - AML Screening: $0.20 per worker
  - Face Search 1:N against your private worker index: Free
  - Baseline total: $0.53 per worker — public price, no minimums
  - Optional Database Validation (licence registry): $0.20 per call, only billed when used
  - First 500 verifications free every month, forever
  - Ongoing AML on active workforce: $0.07 per worker per year (automatic)

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder that bundles ID Verification + Passive Liveness + Face Match 1:1 + Device & IP + AML Screening. For drivers, ALSO add Database Validation and branch on country_of_work.

STEP 1 — Open the worker session at signup

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with KYC + AML (and Database Validation if driver)>",
      "vendor_data": "<your worker id, max 256 chars>",
      "callback_url": "https://<your-app>/gig/onboarding/callback",
      "metadata": {
        "gig_category": "rideshare",
        "country_of_work": "ES",
        "license_number": "<worker's licence number, OCR'd or self-entered>"
      }
    }

  Response: 201 Created with a hosted session URL on the `url` field. Redirect the worker (web or in-app webview). Sub-2-second median verdict on completion.

STEP 2 — Read the signed webhook when the worker finishes

  Didit POSTs to your callback. Session statuses are Title Case With Spaces:

  Body (excerpted, with optional Database Validation included for a driver):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your worker id>",
      "status": "Approved",
      "id_verification": { "status": "Approved", "document_type": "Driver License" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "ip_analysis": { "status": "Approved" },
      "aml": { "status": "Approved", "hits": [] },
      "database_validation": { "status": "Approved", "registry": "DGT" }
    }

  Status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw body bytes with your webhook secret. Re-serialising the parsed JSON breaks the signature.

STEP 3 — Branch on the verdict

  Approved          → activate the worker; let them pick up jobs.
  In Review         → route to ops queue; hold first job until disposition.
  Declined          → block; log the hit detail for compliance.
  Resubmitted       → applicant retried after a soft rejection — re-read.
  Kyc Expired       → session went stale; send a new session URL.

STEP 4 — Re-application defence (Face Search 1:N)

  Every onboarded worker is indexed in your app's private Face Search 1:N index. A banned worker re-applying under a different name + a different document + a different IP is caught in under 200ms on the same /v3/ call (Face Search runs as a workflow step). Set the action on duplicate match to Block, Review, or Approve per app.

STEP 5 — Ongoing AML on the active workforce is automatic

  Every Approved worker is re-screened DAILY by Didit's continuous AML monitoring at $0.07 per worker per year. NO separate endpoint to call — the original session is what gets monitored.

  When a previously-clean worker crosses an AML threshold (new sanction listing, new adverse-media hit, PEP status change), the session status changes to "In Review" or "Declined" automatically and your webhook fires the update. Disable the worker, route to ops.

STEP 6 — Optional licence registry for drivers

  For ride-share and delivery onboardings only, enable Database Validation in the workflow and branch on country_of_work:
    ES → DGT
    UK → DVLA
    US → state DMV (per state)
    BR → DENATRAN

  The check costs $0.20 and is only billed when the workflow step runs. If the country isn't supported yet, the step is skipped — no spurious decline.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.
  - Ongoing AML updates: same session webhook fires when the verdict flips post-onboarding.

  Verify X-Signature-V2 on every payload.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review). Do not lowercase or snake_case them.
  - Database Validation is country-specific — 20+ countries live for driver licences. If the country isn't live, the check is skipped (no spurious decline).
  - 200+ fraud signals are evaluated on every KYC session at no extra cost.
  - The session URL is single-use; if a worker abandons mid-flow, create a new session for the retry.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/core-technology/aml-screening/overview
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.