Search any face.
Across your entire population.

# Didit Face Search 1:N — integrate in 5 minutes

You are integrating Didit's Face Search 1:N (one-to-many biometric search)
module into my_stack. Follow these steps exactly. Every URL, header, and
enum value below is canonical — do not paraphrase or "improve" them.

Face Search 1:N searches a reference face against your entire database of
previously verified users to detect duplicate accounts, blocklisted faces,
and fraud rings. Free forever on every plan — no per-call fee, no minimum.

## 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 (automatic, inside every liveness check)
Best when you want Face Search to run automatically every time a user
verifies. Face Search 1:N is automatically performed during liveness
checks in verification sessions to detect duplicate users and check
against blocklisted faces. No extra wiring needed.

1. Create a workflow that contains the LIVENESS 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
         the JSON object containing feature equal to "LIVENESS"
         (UPPERCASE — strict enum). Face Search runs automatically.

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 the session webhook (see "Webhooks" below). The face_search
   block is included in the session report under decision.face_search.

### Path B — Standalone server-to-server API
Best when you want to search a face on demand — fraud investigation,
manual review tooling, watchlist scan, identity re-auth.

POST https://verification.didit.me/v3/face-search/
Content-Type: multipart/form-data
Body fields:
  - image                  (required, file — single reference face)
  - vendor_data            (optional string, your search id)
  - similarity_threshold   (optional int 0-100, default 70)
  - allow_multiple_faces   (optional bool, default false)

Response: JSON report with matches array, similarity percentages,
blocklist flags, and the standard warnings array.

## 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 (both paths return the same shape)
The face_search object includes:
- status: "Approved" | "Declined" | "In Review"
- total_matches: integer (0 when no match crossed the threshold)
- matches: array of match objects, each with:
    - session_id              UUID of the matching session
    - session_number          integer
    - similarity_percentage   number 0-100
    - vendor_data             your reference data from the original verification
    - verification_date       ISO 8601 timestamp
    - user_details            name, document_type, document_number (masked)
    - match_image_url         signed URL, expires in 60 minutes
    - status                  "Approved" | "Declined" | "In Review"
    - is_blocklisted          boolean
- user_image:
    - entities array (bbox, confidence, age, gender per detected face)
    - best_angle (0 | 90 | 180 | 270) if rotate_image enabled
- warnings: Array of risk, log_type, short_description, long_description

Similarity bands documented:
  90+        Strong match — very likely the same person
  70 – 89    Possible match — may require manual review
  Below 70   Likely different individuals

Auto-decline risks (always enforced by Didit, not configurable):
- NO_FACE_DETECTED       no face in the reference image
- FACE_IN_BLOCKLIST      the reference face matches your face blocklist

Configurable warning:
- MULTIPLE_FACES_DETECTED   tune allow_multiple_faces per application

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: FACE_SEARCH, LIVENESS, ID_VERIFICATION, FACE_MATCH.
- 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"
  (title-cased, space-separated).
- match_image_url is signed and expires after 60 minutes — do not cache it,
  re-fetch from the session if you need it again.

## 6. Pricing reference (public)
- Face Search 1:N is FREE FOREVER on every Didit plan.
- No per-call fee for the standalone POST /v3/face-search/ endpoint.
- No surcharge when bundled inside a LIVENESS workflow.
- 500 free Didit verifications every month on top of that.
- Templates only — your biometric index stores hashed embeddings, never raw
  photos. Encrypted at rest in EU-region AWS.

## 7. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test images: deterministic synthetic faces returned in sandbox (Approved
  by default; trigger Declined by sending a known-blocklisted test face).
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/face-search/overview