Face Search 1:N API: Duplicate Detection

Face Search is a powerful feature that allows you to search for a specific face across all your approved identity verification sessions. This capability helps identify duplicate accounts, prevent fraud, and enhance your security measures. The Academy lesson on reading a verification result reaches face search and block lists at 6:53.

Automatic Face Search Integration

Face Search is automatically performed during liveness checks in verification sessions to detect duplicate users and check against blocklisted faces.

Automatic Duplicate Detection

When a user completes a liveness check during identity verification:

• Their facial biometrics are automatically compared against all previously verified users
• The system identifies potential duplicate accounts based on facial similarity
• Matches are flagged according to your configured similarity thresholds
• You can review and take action on potential duplicate users

Blocklist Integration

Face Search seamlessly integrates with the blocklist feature:

• During verification, faces are automatically checked against your blocklist
• If a match to a blocklisted face is found, the verification is automatically declined
• This prevents previously identified problematic users from creating new accounts
• Helps maintain the integrity of your verification process

The selfie taken during document capture

While the user photographs their document, the front camera takes a selfie of them (Silent Capture). Every time the document is evaluated, that selfie goes through the same 1:N search as the liveness selfie:

• It is compared against your face blocklist and against the users already approved in your application, with the same similarity thresholds and the same precedence as the liveness search.
• A blocklist match raises FRONT_CAMERA_FACE_IN_BLOCKLIST (always Declined) or POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST (always Review). A match with an approved user raises FRONT_CAMERA_DUPLICATED_FACE or POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE, plus FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH when that approved user was verified under a different name, and FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH when that user’s identity document shows a different date of birth. See ID verification warnings.
• The matches are listed in the session details, in the ID verification card, and returned in id_verifications[].document_selfie_face_matches of the session decision. It uses the same entry format as liveness_checks[].matches. The field is null for older sessions or when the search did not run, and an empty array when it ran and found nothing. match_image_url is a presigned URL that expires.
• Only the largest face in the selfie is used, and only when the detector is confident it is a face. One selfie per document is searched: the front-side one, or the back-side one when the front-side selfie holds no clear face.
• The selfie is only compared. Its biometric template is never stored, so later sessions are never matched against it. To ban a person from a session’s selfie, add it to your face blocklist from the session page.

The search has its own switch and its own actions on the ID Verification step, in the step’s Rules tab (Silent Capture Face Search), or with document_selfie_face_search_enabled and the document_selfie_duplicated_face_* actions in the workflow feature config. It is on by default; the duplicated-face action defaults to Approve (the warning is still reported) and the name and document cross-checks default to Review, like their liveness counterparts. The search needs the selfie, so it only runs when Silent Capture is on. Turning Face Search off on the Liveness step turns this search off too: that opt-out is a choice about the person’s face, so it covers every selfie of the session.

The document mismatch rule

The document mismatch rule (DUPLICATED_FACE_DOCUMENT_MISMATCH for the liveness selfie, FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH for Silent Capture) flags a duplicated face only when the matched user’s identity document shows a different date of birth. The same person presenting a different document, for example a passport after an ID card, is not flagged. A renewed document is not flagged either. Two sessions that share the same document number from the same country are never flagged.

Turning automatic Face Search off

Automatic Face Search is on by default for every Liveness step. If your privacy posture calls for it, you can switch it off per workflow from the Liveness step’s Rules tab in the Business Console (Simple and Advanced Mode), or with face_search_enabled: false on the LIVENESS or AGE_ESTIMATION node in the workflow feature config. With the switch off, the liveness selfie is still scored for liveness and compared 1:1 against the document portrait in Face Match, but it never reaches the face index:

• No search runs, so the session gets no duplicate, blocklist or allowlist verdict and its liveness_checks[].matches stays empty. The Duplicated face, name mismatch, document mismatch and cross-organization face rules have nothing to act on and are hidden in the Console.
• No biometric template is stored for the selfie, so later sessions cannot be matched against this one and there is nothing for biometric-template retention to keep after the session is deleted.
• The selfie is not used to resolve a shared biometric person for cross-organization checks.
• The selfie taken during document capture is not searched either (no FRONT_CAMERA_* blocklist or duplicate risk): the opt-out covers every selfie of the session. The ID Verification step’s own switch (see above) can also turn that search off on its own.

Which step the switch belongs to. The switch sits on the step that captures the selfie, so a Liveness or Age Estimation step answers for itself. A Face Match step has none of its own: when a user retakes the selfie there - after you ask them to resubmit that step, for example - the retake follows the Liveness step’s setting, so an opt-out keeps the new selfie out of the index too. If your workflow branches into more than one Liveness step, the setting that applies is the one on the branch the session actually went through, and the cross-organization face read follows that same step. Existing workflows keep today’s behavior until you opt out. The change applies to sessions started after the workflow is saved; templates stored by earlier sessions stay in the index until those sessions are deleted or purged. The switch does not affect the standalone Face Search API, which you call explicitly.

API Access

Face Search functionality is also available through our API, allowing you to:

• Programmatically submit face searches
• Integrate face matching capabilities into your own applications
• Build custom fraud detection workflows
• Create automated systems for duplicate detection

Key Features

• High Accuracy: Advanced biometric algorithms provide reliable match results
• Configurable Thresholds: Customize match sensitivity based on your risk tolerance
• Comprehensive Scanning: Search across all your verified users
• Rapid Results: Process searches quickly even with large user databases
• Privacy-Focused: Matching uses numeric face templates scoped to your application; the index never leaves your tenant

Configurable Thresholds

You can customize search sensitivity by setting different thresholds for similarity scores:

How It Works

Deleted sessions and retained biometric templates

Deleting a session deletes its face embedding by default, so the person drops out of the index and can verify again without a duplicate flag. Applications that delete sessions soon after approval but still need to catch repeat sign-ups can enable biometric-template retention. Didit then keeps one image-free biometric template anchored to the User after the session is deleted, and that template takes part in Face Search and automatic duplicate detection exactly like a live session face. A hit on a retained template is reported with source: "retained_template", the owning User’s vendor_user_id and vendor_data, and a biometric_template_id. It carries no session id, match image, identity details, or session status, because the session that produced the face no longer exists. Retained templates are never blocklisted; face blocklist entries keep their own independent biometric entry. The template stays until its scheduled expiry, User deletion, a privacy-erasure request, or an explicit purge through the Biometric Templates API or Lists → Biometric templates in the Console.

Similarity Percentage

The similarity percentage is the core metric used to determine potential matches:

• High percentage (typically 90% and above): Indicates a strong likelihood that the faces belong to the same person.
• Medium percentage (70-89%): Suggests possible matches that may require further review.
• Low percentage (below 70%): Likely indicates different individuals.

The exact threshold for what constitutes a “match” can be configured based on your security requirements. Increasing the threshold reduces false positives but may increase false negatives.

Use Cases

• Fraud Prevention: Identify users attempting to create multiple accounts
• Enhanced KYC: Add an additional layer of verification to your KYC process
• Regulatory Compliance: Meet requirements for detecting duplicate accounts
• Access Control: Verify user authenticity for high-security areas
• Law Enforcement: Assist authorized agencies in identifying persons of interest