Age-gate without an ID upload. Verify on a selfie. Fall back only when needed.

You are integrating Didit's Age Verification recipe into <my_stack>. Selfie-first age estimation with an adaptive document fallback for the borderline tail. One Didit workflow. Two real endpoints.

  1. Verify age on a selfie. ONE call to the Sessions API runs Age Estimation + Passive Liveness on the same passive frame.
  2. Fall back to a document check ONLY when the estimate sits in the borderline band you define. Same Sessions API workflow handles the fallback automatically.

Bundle pricing (public):
  - Age Estimation: $0.10 per check (Sessions API or standalone)
  - ID Verification fallback: $0.15 per check, only when triggered
  - Typical blended cost lands near $0.115 per user (~90% finish on the selfie, ~10% touch the document fallback)
  - 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 and your webhook secret.
  - A workflow_id from the Workflow Builder. The workflow must contain the AGE_ESTIMATION feature, and (recommended) the ID_VERIFICATION feature with adaptive_id_verification enabled so the borderline tail routes through automatically.

STEP 1 — Build the adaptive workflow once

  POST https://verification.didit.me/v3/workflows/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_label": "age_gate_uk_fr",
      "features": [
        { "feature": "AGE_ESTIMATION" },
        { "feature": "ID_VERIFICATION" }
      ],
      "age_estimation_decline_threshold": 18,
      "face_liveness_score_decline_threshold": 30,
      "adaptive_id_verification": true
    }

  Notes:
    - "AGE_ESTIMATION" and "ID_VERIFICATION" are exact, case-sensitive feature names.
    - age_estimation_decline_threshold defaults to 18; set 21 for US alcohol, 19 for South Korea, etc.
    - adaptive_id_verification = true tells Didit to invoke the document fallback automatically when the estimate sits inside the borderline band.

STEP 2 — Open an age-verification 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>/age-gate/callback",
      "metadata": {
        "purpose": "age_gate",
        "surface": "<the page or feature being gated>"
      }
    }

  Response: 201 Created with the hosted session_url. Redirect the user to it. The hosted flow opens the front camera, captures one passive frame, runs Age Estimation + Passive Liveness in sub-2-seconds, and either returns a verdict or routes the user into the document fallback automatically.

STEP 3 — Read the signed webhook on session completion

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

  Body (excerpted for an Age Estimation only finish):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": {
        "status": "Approved",
        "method": "PASSIVE",
        "score": 92,
        "age_estimation": 27.3,
        "warnings": []
      }
    }

  Body (excerpted when the document fallback fired):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": { "status": "Approved", "age_estimation": 17.9, "warnings": [{ "code": "AGE_NOT_DETECTED" }] },
      "id_verification": {
        "status": "Approved",
        "date_of_birth": "1998-03-21",
        "age": 27,
        "document_type": "Passport",
        "issuing_state": "GBR"
      }
    }

  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.

  Warning catalog:
    - AGE_BELOW_MINIMUM        estimated or computed age below the threshold
    - AGE_NOT_DETECTED         unable to estimate age (lighting / quality)
    - LOW_LIVENESS_SCORE       passive-liveness score below threshold
    - NO_FACE_DETECTED         no face in the capture
    - LIVENESS_FACE_ATTACK     presentation attack suspected
    - POSSIBLE_DUPLICATED_FACE same face previously verified

STEP 4 — Branch your surface on the final verdict

  Approved      → grant access to the gated surface.
  Declined      → render the regulator-required age-gate notice.
  In Review     → hold; an analyst case is open in the Business Console.
  Not Finished  → user abandoned; safe to re-prompt.

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

  POST https://verification.didit.me/v3/age-estimation/
  Headers:
    x-api-key: <your api key>
  Body (multipart/form-data):
    user_image                              <single passive selfie>
    age_estimation_decline_threshold        18    (optional, integer)
    face_liveness_score_decline_threshold   30    (optional, integer)

  Branch on the borderline band yourself, then optionally call:

  POST https://verification.didit.me/v3/id-verification/
  Body (multipart/form-data):
    front_image  <required>
    back_image   <optional>
    vendor_data  <optional, your user id>

  This path is useful for native onboarding apps that capture the selfie locally.

CONSTRAINTS
  - Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
  - Feature enum is UPPERCASE: AGE_ESTIMATION, ID_VERIFICATION, LIVENESS, FACE_MATCH, AML, IP_ANALYSIS.
  - 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.
  - Reference image URLs are signed and expire in 60 minutes. Store only the verdict + score; never the biometric media unless retention is explicitly enabled for fraud defence.
  - 200+ fraud signals are evaluated on every session at no extra cost — surface the score via the session decision payload, do not re-query.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.
  - Verify X-Signature-V2 on every payload.

Read the docs:
  - https://docs.didit.me/core-technology/age-estimation/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.