Face match

The FACE_MATCH module performs a 1:1 biometric comparison of the document portrait (from ID verification or the NFC chip) against the live selfie captured during liveness. It answers "is this the same person as the document?" — liveness answers "is this a live person?"; a real workflow runs both.

How the decision is made

The engine compares face embeddings and returns a matched flag together with a calibrated similarity percentage:

• The model's own cosine decision threshold is authoritative for matched. Genuine-match cosines sit well below 100% (AdaFace ~0.3–0.7), so the engine gates on the model's calibrated threshold rather than a naive similarity floor — a hard percentage floor would wrongly reject true matches.
• matched true → approved. matched false → declined.
• A capture problem (quality gate tripped, or no face found in the selfie) is retryable — the applicant is asked to retake. Only after exhausted retries does a capture problem escalate to review rather than a decline.

Review bands (min_similarity)

A tenant can set a min_similarity floor. It is a review band, not a decline: the biometric model decides same-person vs impostor; the floor only escalates a weak-but-genuine match to an operator instead of auto-approving it (similarity_below_minimum).

Precedence:

1. A per-document-type rule — ID_VERIFICATION config document_rules[<type>].min_similarity — wins, taken from the document this node matched. Licence portraits and passport photo pages warrant different bands.
2. Otherwise the workflow-wide min_similarity on the face-match step applies.

In a repeated-ID graph, the per-type band comes from the document wired to this face-match node, not the globally-latest upload — so a sibling document's band never leaks across.

How scoring and decisioning works

Common decline / review reasons

Reference image sourcing

A workflow whose Face Match has no document step compares the selfie with a reference portrait. You can pass one when you create the session (reference.face_image — see Create a session); otherwise switch on Reference image sourcing in the Face Match node's config and the flow finds one itself, from three trusted sources in a fixed order:

The applicant can never supply their own reference — not configurable, at any tier; the hosted flow refuses any image it is sent (403 applicant_reference_not_allowed).

The lookups run as the applicant reaches the selfie step. When tiers 1–2 come up empty, the applicant waits on a "preparing your verification" screen while operators are alerted — a console notification, and an Awaiting reference badge (and filter) on the Verifications list. The wait ends when an operator supplies the photo, lets the applicant continue without one, or the node's operator timeout runs out (15 minutes by default). Without a reference, Face Match is held for review. In a workflow with a document step nothing waits: the document portrait is the compared face, and a sourced reference feeds the independent reference bands instead.

Every accepted photo — from any tier — must be a JPEG or PNG showing exactly one face; it is cropped with the same logic that isolates a document portrait, stored as the session's reference, and matched through the normal reference flow. The session then records where it came from:

"metadata": {
  "reference": {
    "authenticated": true,
    "vendor_identity": {
      "source": "external_system",
      "tier": 1,
      "action_id": "cbs_lookup",
      "action_name": "CBS customer photo lookup",
      "node_id": "FACE_MATCH",
      "at": "2026-09-24T08:01:10+00:00"
    }
  }
}

source is external_system (with action_id / action_name), identity_record (with matched_by and reference_session_id, the prior verification) or operator (with method — capture or upload — and the operator's id, email and role). The Face Match result carries the same object as data.reference_source, and an operator's capture or skip is on the verification's audit trail.

1:N face search (duplicate detection)

Beyond the 1:1 module, the engine can rank your tenant's enrolled identities whose face matches a probe photo — the same embedding engine, used for duplicate-account detection. It runs automatically during a session (a duplicate face can flag the session for review) and is also exposed as the stateless /v3/tools/face-search/ tool:

curl -X POST "$TF_BASE_URL/v3/tools/face-search/" \
  -H "x-api-key: $TF_API_KEY" -H "Content-Type: application/json" \
  -d '{"image_base64":"<jpg/png base64>","threshold":0.35,"top_k":12}'

const res = await fetch(`${process.env.TF_BASE_URL}/v3/tools/face-search/`, {
  method: "POST",
  headers: { "x-api-key": process.env.TF_API_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({ image_base64: probeBase64, threshold: 0.35, top_k: 12 }),
});
const { matches } = await res.json();

import requests

resp = requests.post(
    f"{BASE_URL}/v3/tools/face-search/",
    headers={"x-api-key": API_KEY},
    json={"image_base64": probe_base64, "threshold": 0.35, "top_k": 12},
    timeout=15,
).json()
matches = resp["matches"]

threshold clamps to 0.2–0.95 (default 0.35), top_k ≤ 50 (default 12). It returns ranked matches with each identity's individual_id, external_user_id, status, score and thumbnail. Use it to run a new applicant's selfie against the existing population before approving them.

What the searchable gallery contains

Two face sources are enrolled into the 1:N gallery: selfies captured live during a session, and photos you bulk-imported via identity import — being findable by 1:N is the whole point of an import. Document portraits, vendor reference faces and liveness stills are deliberately not in the gallery, so a hit always means "we hold this face as this person", never "this face appeared on some document."

Result shape

FACE_MATCH returns matched, the similarity score, source (DOCUMENT) and target (SELFIE), and any warnings (e.g. face_mismatch, similarity_below_minimum). Read it from GET /v3/session/<id>/ or decision_v3.face_matches on the decision endpoint.

{
  "feature": "FACE_MATCH",
  "status": "approved",
  "score": 78.4,
  "warnings": [],
  "data": {
    "matched": true,
    "similarity": 78.4,
    "source": "DOCUMENT",
    "target": "SELFIE"
  }
}

curl -s "$TF_BASE_URL/v3/session/$SESSION_ID/" \
  -H "x-api-key: $TF_API_KEY" \
  | jq '.results[] | select(.feature == "FACE_MATCH")'

const session = await fetch(`${process.env.TF_BASE_URL}/v3/session/${sessionId}/`, {
  headers: { "x-api-key": process.env.TF_API_KEY! },
}).then((r) => r.json());
const faceMatch = session.results.find((r: any) => r.feature === "FACE_MATCH");
console.log(faceMatch.data.matched, faceMatch.data.similarity);

import requests

session = requests.get(
    f"{BASE_URL}/v3/session/{session_id}/",
    headers={"x-api-key": API_KEY}, timeout=15,
).json()
face_match = next(r for r in session["results"] if r["feature"] == "FACE_MATCH")
print(face_match["data"]["matched"], face_match["data"]["similarity"])

FAQ

Related