Age-gate any user.
Without asking them for an ID.

# Didit Age Estimation — integrate in 5 minutes

You are integrating Didit's Age Estimation module into <my_stack>. Follow
these steps exactly. Every URL, header, and enum value below is canonical
— do not paraphrase or "improve" them.

## 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/
  (returns an API key bound to the workspace + application).

## 2. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI)
Best when you want Didit to handle the camera, framing, low-light
fallback, mobile handoff, and accessibility for you. Required if you want
Adaptive Age Verification (auto-fall-back to ID for borderline cases).

1. Create a workflow that contains the AGE_ESTIMATION feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the single entry
         { feature: "AGE_ESTIMATION" }   (UPPERCASE — strict enum)
   Optional config:
     - age_estimation_decline_threshold (default 18)
     - face_liveness_score_decline_threshold (default 30)
     - adaptive_id_verification (when true, borderline cases trigger ID
       verification fallback governed by per-country age restrictions on
       the ID Verification step)
     - per_country_age_restrictions (map of country -> min / max age,
       with optional state-level overrides)

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id).
   Response: session_url — redirect the user to it.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone server-to-server API
Best when you already have a selfie image (mobile SDK capture, native
onboarding app, reseller pipeline) and only need a numeric age estimate
plus passive-liveness verdict on it. No adaptive ID fallback on this
path — wire that yourself if you need it.

POST https://verification.didit.me/v3/age-estimation/
Content-Type: multipart/form-data
Body fields:
  - user_image                              (required, file — single selfie)
  - age_estimation_decline_threshold        (optional integer 0-100, default 18)
  - face_liveness_score_decline_threshold   (optional integer 0-100, default 30)
  - rotate_image                            (optional boolean, default false)
  - save_api_request                        (optional boolean, default true)
  - vendor_data                             (optional string, your user id)

Response: JSON with request_id, age_estimation block, created_at.

## 3. Webhooks (Path A only — Path B returns synchronously)
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  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.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 4. Reading the report

### Path A (session) — age_estimation lives on the liveness object
The liveness object on the session report includes age_estimation as a
number-of-years field on the same selfie capture:
- liveness.status           "Approved" | "Declined" | "In Review" | "Not Finished"
- liveness.method           "PASSIVE" | "FLASHING" | "ACTIVE_3D"
- liveness.score            number 0-100  (normalized liveness score)
- liveness.reference_image  signed URL to the captured selfie (60-minute TTL)
- liveness.age_estimation   estimated age in years (e.g. 24.3)
- liveness.warnings         Array of risk objects (see below)

### Path B (standalone) — top-level age_estimation block
- request_id                          uuid
- age_estimation.status               "Approved" | "Declined" | "In Review"
- age_estimation.method               "PASSIVE"
- age_estimation.score                number 0-100  (passive-liveness score)
- age_estimation.age_estimation       estimated age in years (e.g. 27.33)
- age_estimation.user_image.entities  array of detected faces, each with
                                       age, bbox, confidence, gender
- age_estimation.user_image.best_angle integer
- age_estimation.face_quality         0-100 face image quality score
- age_estimation.face_luminance       0-100 face luminance score
- age_estimation.warnings             Array of risk objects (see below)
- created_at                          ISO8601

### Warning catalog (both paths)
- AGE_BELOW_MINIMUM            estimated age below the configured threshold
- AGE_NOT_DETECTED             unable to estimate age (quality / lighting)
- LOW_LIVENESS_SCORE           passive-liveness score below threshold
- NO_FACE_DETECTED             no face in the capture
- LIVENESS_FACE_ATTACK         presentation attack suspected
- FACE_IN_BLOCKLIST            face matches an entry in your blocklist
- POSSIBLE_DUPLICATED_FACE     face matches a previously verified face

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: AGE_ESTIMATION, LIVENESS, ID_VERIFICATION,
  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).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- Reference image / video URLs are signed and expire in 60 minutes —
  store only the verdict + score, never the biometric media.

## 6. Pricing reference (public)
- AGE_ESTIMATION standalone or bundled inside a workflow: $0.10 per check
- Adaptive fallback to ID Verification (when triggered): $0.15 per check
- Bundled in a full KYC workflow alongside Liveness + ID + IP: $0.33 per session
- 500 free verifications every month, forever, on every account.

## 7. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test images: deterministic synthetic faces returned in sandbox
  (predictable estimated age band; trigger AGE_BELOW_MINIMUM by sending
  the canonical "minor" test image).
- Switch to live: flip the application environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/age-estimation/overview