Recover a lost account with a face check.

You are integrating Didit into an account-recovery flow. Replace knowledge-based recovery (security questions, SMS OTP, support-rep verification) with a biometric re-match against the user's enrolment selfie. ONE Didit session, two checks:

  - Passive Liveness — make sure the recovery selfie is a real human, not a print / screen / mask / deepfake.
  - Face Match 1:1 — match the recovery selfie against the user's enrolment selfie. If similarity is above your threshold, the recovery is approved.

Bundle pricing (verified live, 2026-05-16):
  - Passive Liveness: $0.10 per recovery
  - Face Match 1:1: $0.05 per recovery
  - Total: ~$0.15 per recovery — public price, no minimums
  - First 500 verifications free every month, forever
  - SMS / WhatsApp One-Time Passcode (OTP) fallback: $0.03 per OTP (when biometric isn't possible)

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.
  - User's enrolment selfie on file — captured during initial KYC via a previous /v3/session/. Stored under your tenant in encrypted form.
  - A workflow_id from the Workflow Builder that runs Passive Liveness + Face Match 1:1 against the stored reference.

STEP 1 — Trigger recovery on the right signal

  Recovery is gated by your risk policy. Typical triggers:

  - User clicks "Forgot password" — always.
  - Sign-in from a new device + new IP country at the same time.
  - Sign-in after account dormancy (e.g. 180+ days).
  - Sensitive action: large withdrawal, payout to a new beneficiary, account-settings change.

  Each trigger opens a Didit session.

STEP 2 — Open the recovery session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with Passive Liveness + Face Match against enrolment selfie>",
      "vendor_data": "<your user id, max 256 chars>",
      "callback": "https://<your-app>/account/recovery/callback",
      "metadata": {
        "trigger": "forgot_password",
        "device_fingerprint": "<your device fingerprint>",
        "ip_country": "ES"
      },
      "portrait_image": "<base64 JPEG of the user's enrolment selfie, ≤ 1 MB — REQUIRED when the workflow has FACE_MATCH active; the recovery flow matches the new live selfie against this stored reference>"
    }

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

STEP 3 — Read the signed webhook on the verdict

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

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 }
    }

  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 bytes with your webhook secret.

STEP 4 — Branch on the verdict

  Approved          → unlock recovery: send the password-reset email, register the new device, complete the sensitive action.
  In Review         → soft-fail the recovery, route to support for human review.
  Declined          → block the recovery; log the hit. Could be a printed-photo or screen-replay attack — surface to security.
  Resubmitted       → user retried after a soft rejection — re-read.
  Kyc Expired       → reference selfie has aged out (per your retention policy) — fall back to documented recovery flow.

STEP 5 — Fallback for users who can't take a selfie

  Camera missing, low light, hardware refused permission. Two graceful fallbacks:

  - SMS / WhatsApp / Telegram One-Time Passcode (OTP) via Didit Phone Verification, $0.03 per OTP.
  - Email magic link via your existing transactional email provider, $0.03 per email.
  - Authenticator app — Time-based One-Time Password (TOTP) or FIDO2 hardware key, free.

  Configure the fallback chain in the Workflow Builder. Selfie always tried first.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.

  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.
  - The recovery similarity threshold is configurable per app — start at 0.85, tune up for high-assurance apps (banks, brokerages) and down for low-friction consumer apps.
  - Liveness is a Presentation Attack Detection (PAD) Level 1 model — defeats prints, screens, masks, deepfakes on consumer cameras. Active liveness (head-tilt prompts) is available for higher-friction higher-assurance flows at $0.15.
  - The user's enrolment selfie must have been captured by Didit (any prior /v3/session/ with face capture). Bring-your-own enrolment image is roadmap.
  - Default audit retention is 5 years configurable in the Business Console.

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