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

1:N face search (duplicate detection)

Beyond the 1:1 module, the engine can rank your tenant's enrolled identities whose selfie 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.

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