Prove a real human. Not a deepfake. Not an LLM.

You are integrating Didit's Proof of Human gate into <my_stack>. Block AI agents, deepfakes, masks, and duplicate accounts from human-only surfaces — signup, voting, contests, marketplaces, dating. Two endpoints, one verdict.

  1. Prove a real human is present (Liveness). ONE call to the Sessions API runs a Presentation Attack Detection (PAD)-certified passive selfie and returns a verdict in sub-2-seconds.
  2. Prove the human is unique (Face Search 1:N). Same Sessions API workflow runs Face Search 1:N against your account's private face index.

Pricing (public):
  - Passive Liveness: $0.10 per check
  - Active 3D Liveness: $0.15 per check (motion challenge — use for high-sensitivity flows)
  - Face Search 1:N: free, included
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with Hash-based Message Authentication Code (HMAC) SHA-256 verification using the X-Signature-V2 header.
  - A workflow_id from the Workflow Builder that contains the LIVENESS feature, and (recommended) FACE_MATCH and IP_ANALYSIS so Sybil dedupe + agent / bot signals come in on the same verdict.

STEP 1 — Build the Proof of Human workflow once

  POST https://verification.didit.me/v3/workflows/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_label": "proof_of_human",
      "features": [
        { "feature": "LIVENESS", "config": { "method": "PASSIVE" } },
        { "feature": "FACE_MATCH" },
        { "feature": "IP_ANALYSIS" }
      ],
      "face_liveness_score_decline_threshold": 30
    }

  Notes:
    - LIVENESS, FACE_MATCH, IP_ANALYSIS are exact, case-sensitive feature names.
    - method enum: PASSIVE (one frame) · FLASHING (3D flash) · ACTIVE_3D (action + flash). Use ACTIVE_3D for the highest-sensitivity surfaces (large-value account creation, voting, contest finals).

STEP 2 — Open a Proof of Human session per user

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<the workflow_id from step 1>",
      "vendor_data": "<your internal user id>",
      "callback": "https://<your-app>/proof-of-human/callback",
      "metadata": {
        "surface": "<signup | vote | contest | marketplace | dating>"
      }
    }

  Response: 201 Created with the hosted session_url. Redirect the user. The hosted UI opens the front camera, captures one passive frame (or a short motion challenge for ACTIVE_3D), runs Liveness + Face Search 1:N, returns the verdict in sub-2-seconds.

STEP 3 — Read the signed verdict on the webhook

  Body (excerpted for a clean human):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": {
        "status": "Approved",
        "method": "PASSIVE",
        "score": 96,
        "warnings": []
      },
      "face": {
        "status": "Approved",
        "similarity_score": null,
        "matches": []
      },
      "ip_analysis": { "status": "Approved" }
    }

  Body (excerpted for a duplicate):
    {
      "status": "In Review",
      "liveness": { "status": "Approved", "score": 94 },
      "face": {
        "status": "In Review",
        "matches": [
          { "vendor_data": "user_8124", "similarity_score": 0.97 }
        ],
        "warnings": [{ "code": "POSSIBLE_DUPLICATED_FACE" }]
      }
    }

  Verify X-Signature-V2 BEFORE trusting the body — HMAC SHA-256 of the raw bytes with your webhook secret.

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

  Liveness warning catalog:
    - LIVENESS_FACE_ATTACK     PAD attack suspected (print / replay / mask / GAN)
    - LOW_LIVENESS_SCORE       score below threshold
    - NO_FACE_DETECTED         no face in the capture
    - AGE_NOT_DETECTED         capture quality too low for age signal
    - POSSIBLE_DUPLICATED_FACE same face previously verified on your account

STEP 4 — Branch your surface on the final verdict

  Approved      → grant access to the human-only surface.
  Declined      → block; log the rejected agent / spoof attempt.
  In Review     → hold; show a review-pending banner, route to ops queue.
  Not Finished  → user abandoned; safe to re-prompt.

STEP 5 — Alternate path (server-to-server, when you have the selfie)

  POST https://verification.didit.me/v3/passive-liveness/
  Headers:
    x-api-key: <your api key>
  Body (multipart/form-data):
    image    <single front-camera selfie>

  Then dedupe:

  POST https://verification.didit.me/v3/face-search/
  Body (multipart/form-data):
    image          <same selfie>
    vendor_data    <your user id>

  Use the standalone path for native onboarding apps that capture the selfie locally. Active 3D liveness REQUIRES the hosted session — it needs the motion challenge to run.

CONSTRAINTS
  - Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
  - Feature enum is UPPERCASE: LIVENESS, FACE_MATCH, IP_ANALYSIS, ID_VERIFICATION, AML, AGE_ESTIMATION.
  - Method enum is UPPERCASE: PASSIVE, FLASHING, ACTIVE_3D.
  - Auth header is x-api-key (lowercase, hyphenated).
  - Webhook signature header is X-Signature-V2 (NOT X-Signature).
  - Status casing matches exactly: Approved, Declined, In Review, Expired, Not Finished, Resubmitted, Kyc Expired, Abandoned.
  - 200+ fraud signals are evaluated on every session at no extra cost.

PRO TIP
  - Bind a Reusable Credential to each approved user. The next Didit-powered surface that needs the same gate consumes the credential at zero cost — the Proof of Human "compounds" across the network.

Read the docs:
  - https://docs.didit.me/core-technology/liveness/overview
  - https://docs.didit.me/core-technology/face-search/overview
  - https://docs.didit.me/sessions-api/create-session
  - 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.