Bind a face to an ID.
In half a second.

# Didit Face Match 1:1 — integrate in 5 minutes

You are integrating Didit's Face Match 1:1 (selfie vs. reference image)
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 selfie capture, real-time framing,
mobile handoff, and accessibility for you. Inside a Know Your Customer (KYC) workflow,
Face Match runs automatically against the portrait extracted from the
ID document the user uploads in the same session.

1. Create a workflow that contains the FACE_MATCH feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with FACE_MATCH plus any
         other features the same session needs (typically
         ID_VERIFICATION and LIVENESS for full KYC). Feature names
         are UPPERCASE — strict enum.
   Optional config: review_threshold and decline_threshold for the
         LOW_FACE_MATCH_SIMILARITY warning (numbers 0–100).

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 two face images and just need a similarity
score (re-auth at sensitive actions, employee badge access, cross-app
identity binding, periodic re-verification).

POST https://verification.didit.me/v3/face-match/
Content-Type: multipart/form-data
Body fields:
  - source_image  (required, file — the live selfie)
  - target_image  (required, file — the reference image, e.g. ID portrait
                   or a stored enrollment frame)
  - vendor_data   (optional string, your user id)

Response: synchronous JSON report with the similarity score and warnings
array. No webhook needed.

## 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_match object includes:
- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- score: number 0-100 (normalized similarity score)
- source_image_session_id: the verification session that produced the
  live selfie (Path A) or null (Path B)
- source_image: signed URL to the live selfie (expires in 1 hour)
- target_image: signed URL to the reference image (expires in 1 hour)
- warnings: Array<{ risk, log_type, short_description, long_description }>

Auto-decline risks (always enforced by Didit, not configurable):
- NO_REFERENCE_IMAGE   (no reference image available to compare against)

Configurable risks (action per workflow — Decline, Review, or Approve):
- LOW_FACE_MATCH_SIMILARITY
    Tune two thresholds per application:
      review_threshold  → score below this goes to "In Review"
      decline_threshold → score below this is auto-declined

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: FACE_MATCH, ID_VERIFICATION, LIVENESS, AML, IP_ANALYSIS.
- 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 and source image URLs in the response expire in 60 minutes.
  Persist only the score and status; re-fetch images on demand if your
  audit policy needs them.

## 6. Pricing reference (public)
- Standalone POST /v3/face-match/: $0.05 per match.
- Bundled inside a full KYC workflow with ID Verification + Passive
  Liveness + Device & IP Analysis: $0.33 per session (Face Match included).
- 500 free checks 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
  (Approved by default; trigger Declined by sending a mismatched pair).
- Switch to live: flip the application's environment toggle in console.

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