Didit Face Match API

Didit Face Match API

Overview

Compares two facial images to determine whether they show the same person. Returns a similarity score (0-100) and an Approved / Declined status.

Key constraints:

• Allowed file extensions: tiff, jpg, jpeg, png, webp (no PDF)
• Maximum file size: 5 MB per image (images are compressed to about 0.5 MB before processing)
• Both user_image and ref_image are required
• Submit one clear, front-facing, well-lit face per image for best results

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: Approved only when the score is strictly above face_match_score_decline_threshold (default 30). A score at or below it returns Declined with LOW_FACE_MATCH_SIMILARITY. If no face pair can be scored, the call still returns HTTP 200 with Declined and NO_REFERENCE_IMAGE. There is no In Review on this endpoint; only the threshold is configurable.

Face search index: this endpoint never enrolls faces and never runs blocklist or duplicate screening. Use POST /v3/passive-liveness/ (didit-liveness-detection) or POST /v3/face-search/ (didit-face-search) for those.

Saving (save_api_request, default true): the call is saved as an API session (Business Console, GET /v3/session/{request_id}/decision/, status.updated webhook) and both images are stored as the session's face-match source and target images. With false nothing is stored and request_id cannot be looked up.

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

Capabilities: similarity scoring, configurable decline threshold, face bounding boxes with model-estimated age and gender per face (informational), optional rotation for non-upright faces.

API Reference: https://docs.didit.me/standalone-apis/face-match Feature Guide: https://docs.didit.me/core-technology/face-match/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?)

If you don't have a Didit API key, create one in 2 API calls:

1. Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "[email protected]", "password": "MyStr0ng!Pass"}
2. Check email for a 6-character verification code
3. Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "[email protected]", "code": "A3K9F2"}. The key is in the response at application.api_key.