Didit Face Search API (1:N)

Didit Face Search API (1:N)

Overview

Searches the largest face in an image against your application's face search index and returns up to 5 ranked matches above the similarity floor, plus blocklist and duplicate warnings.

What is searched: faces enrolled from verification sessions of any status, saved standalone calls (e.g. Passive Liveness or Age Estimation with save_api_request=true), faces uploaded directly to User profiles, faces on your lists (blocklist, allowlist), and image-free biometric templates you chose to retain on a User. Faces enrolled by earlier Face Search calls are never returned, so repeated searches do not match each other.

Search modes (search_type):

• most_similar (default): ranks every enrolled face by similarity. Use for deduplication and fraud-ring investigation.
• blocklisted_or_approved: only blocklisted faces, allowlisted faces, faces from approved sessions, imported User faces and retained templates, with blocklisted entries ranked first. Use for blocklist screening.

Key constraints:

• Allowed file extensions: tiff, jpg, jpeg, png, webp (no PDF)
• Maximum file size: 5 MB (images are compressed to about 0.5 MB before processing)
• The image must contain a detectable face, otherwise HTTP 400 {"error": "No face detected in the image"}
• With several faces the largest one is searched and MULTIPLE_FACES_DETECTED is added
• vendor_data does not exclude the same user's earlier faces from the results (unlike Passive Liveness)

Pricing: $0.05 (per successful call; standalone calls have no free tier). These are the list prices until 1 November 2026, when Didit pricing changes and the 500 free checks a month become $10 of free credit a month. Check didit.me/pricing for current prices.

Decision: Declined only when FACE_IN_BLOCKLIST or POSSIBLE_FACE_IN_BLOCKLIST fires; otherwise Approved. Duplicate and multiple-face warnings never decline, and there is no In Review. Approved does not mean the face is new: check total_matches and the duplicate warnings. This endpoint returns no liveness verdict (use didit-liveness-detection for that).

Saving and enrollment (save_api_request, default true): the call is saved as an API session (Business Console, GET /v3/session/{request_id}/decision/, status.updated webhook), match_image_url values are presigned URLs, and the searched face is enrolled into the index (but never returned by later searches). With false nothing is stored, the face is not enrolled, and match_image_url values are internal storage paths that cannot be downloaded.

Similarity guidance: the Face Search docs read 90%+ as a strong likelihood of the same person and 70-89% as a possible match that may need review. Didit's own verdict is the warning: DUPLICATED_FACE / FACE_IN_BLOCKLIST for strong matches, POSSIBLE_DUPLICATED_FACE / POSSIBLE_FACE_IN_BLOCKLIST for weaker ones.

Sandbox: sandbox API keys return a static Approved payload after request validation; nothing is saved or billed.

API Reference: https://docs.didit.me/standalone-apis/face-search Feature Guide: https://docs.didit.me/core-technology/face-search/overview

Authentication

Every request needs the x-api-key header. Use your application's API key from the Didit Business Console under Developers > API keys, or create an account and key programmatically (see Getting Started). Named keys with custom access need Sessions write to run standalone checks; a key limited to some workflows or to approved sessions cannot run them.

Getting Started (No Account Yet?)