cURL

curl -X POST 'https://verification.didit.me/v3/face-match/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'ref_image=@./id_portrait.jpg' \
  -F 'face_match_score_decline_threshold=50' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'

{
  "request_id": "f9f5a777-8002-44c6-baaf-128bcfd6e226",
  "face_match": {
    "status": "Approved",
    "score": 99.41,
    "user_image": {
      "entities": [
        {
          "bbox": [
            661,
            728,
            1688,
            2188
          ],
          "confidence": 0.732973,
          "age": 26.91,
          "gender": "male",
          "race": null
        }
      ],
      "best_angle": 0
    },
    "ref_image": {
      "entities": [
        {
          "bbox": [
            653,
            745,
            1691,
            2185
          ],
          "confidence": 0.722082,
          "age": 27,
          "gender": "male",
          "race": null
        }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": {
    "flow": "login"
  },
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

Biometrics & Face

Face Match

Compare two face images (1:1) and get back a similarity score (0–100) plus an Approved/Declined status.

How it works. Both images are decoded and analyzed by a biometric model (set rotate_image=true if captures may be sideways or upside down), then a similarity score between the two faces is computed. A score strictly above face_match_score_decline_threshold (default 30) returns status: "Approved"; a score at or below it returns Declined with a LOW_FACE_MATCH_SIMILARITY warning. If no face pair can be scored at all, the call still returns 200 with status: "Declined" and a NO_REFERENCE_IMAGE warning — score is null on the default save path, or 0 with save_api_request=false. Submit one clear, front-facing face per image for best results.

Billing. Each 200 response consumes one Face Match API credit (standalone APIs have no free tier). When the organization’s balance cannot cover the call, the endpoint returns 403 with the not-enough-credits error before any image processing.

Session persistence (save_api_request, default true). When true, the call is persisted as an API-type session: it appears in the Business Console, the returned request_id is a real session id you can pass to GET /v3/session/{sessionId}/decision/, both images are stored as the session’s face-match source/target images, and a status.updated webhook is emitted to your configured webhook endpoints. When false, nothing is stored and request_id is a one-off correlation UUID that cannot be looked up later.

Face search index. This endpoint never enrolls faces into your face search index and never runs blocklist or duplicate screening — use POST /v3/passive-liveness/ or POST /v3/face-search/ for those.

Sandbox. Sandbox API keys skip all processing and billing: after request validation (malformed input still returns 400), the endpoint returns a static Approved mock payload, no session is persisted, and no credits are consumed.

Authentication. Send your application’s API key in the x-api-key header. Missing or invalid credentials return 403 ({"detail": "You do not have permission to perform this action."}) — this API never returns 401.

Rate limit. Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns 429.

POST

face-match

cURL

curl -X POST 'https://verification.didit.me/v3/face-match/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'ref_image=@./id_portrait.jpg' \
  -F 'face_match_score_decline_threshold=50' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'

{
  "request_id": "f9f5a777-8002-44c6-baaf-128bcfd6e226",
  "face_match": {
    "status": "Approved",
    "score": 99.41,
    "user_image": {
      "entities": [
        {
          "bbox": [
            661,
            728,
            1688,
            2188
          ],
          "confidence": 0.732973,
          "age": 26.91,
          "gender": "male",
          "race": null
        }
      ],
      "best_angle": 0
    },
    "ref_image": {
      "entities": [
        {
          "bbox": [
            653,
            745,
            1691,
            2185
          ],
          "confidence": 0.722082,
          "age": 27,
          "gender": "male",
          "race": null
        }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": {
    "flow": "login"
  },
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

Authorizations

x-api-key

string

header

required

Body

multipart/form-data

user_image

file

required

Live or candidate face image to verify (e.g. a selfie). Submit a single front-facing photo with the subject's face clearly visible and well lit. Allowed extensions: tiff, jpg, jpeg, png, webp. Maximum upload size: 5 MB (larger files are rejected with 400). Images are automatically compressed to ~0.5 MB before processing, so very high resolutions do not improve accuracy.

ref_image

file

required

Reference face image to compare against (e.g. an ID document portrait or a previously enrolled photo). Same format and size limits as user_image.

face_match_score_decline_threshold

number<float>

default:30

Similarity threshold (0–100) that drives the response status. A computed score at or below this value sets status to Declined and adds a LOW_FACE_MATCH_SIMILARITY warning; a score strictly above it returns Approved. Default 30 is permissive — raise it (e.g. 50–60) for stricter verification. Values outside 0–100 return 400.

Required range: 0 <= x <= 100

Example:

50

rotate_image

boolean

default:false

When true, the service tries the input images in 90-degree increments (0, 90, 180, 270) and uses the orientation that yields the best face detection — useful for mobile captures with missing EXIF orientation. Adds latency, so only enable it if you cannot guarantee upright images.

Example:

false

save_api_request

boolean

default:true

When true (default), persists the call as an API-type session — visible in the Business Console, retrievable via GET /v3/session/{sessionId}/decision/ using the returned request_id, and announced through a status.updated webhook. When false, nothing is stored and request_id is a transient UUID for response correlation only.

Example:

true

vendor_data

string

Optional opaque string (your internal user id, email, UUID…) stored on the persisted session and echoed back in the response. Use it to correlate API calls with your own records and to filter sessions later.

Example:

"user-123"

metadata

object

Optional JSON object stored with the session (when save_api_request=true) and echoed back in the response. In multipart requests, send it as a JSON-encoded string field (e.g. metadata={"flow":"login"}) — it is parsed into an object.

Example:

{ "flow": "login", "device_id": "abc123" }

Response

Face match computed. face_match.score is a 0–100 float (two decimals); status is Approved when the score is strictly above face_match_score_decline_threshold, otherwise Declined with an explanatory warning. A low similarity or unscorable pair still returns 200 — inspect face_match.status and face_match.warnings, not just the HTTP code. When save_api_request=true, request_id is the persisted session id.

request_id

string<uuid>

Persisted session id when save_api_request=true (usable with GET /v3/session/{sessionId}/decision/); otherwise a transient correlation UUID.

face_match

object

Show child attributes

vendor_data

string | null

Echo of the vendor_data you sent, or null.

metadata

object

Echo of the metadata object you sent, or null.

created_at

string<date-time>

ISO 8601 timestamp (UTC) of when the response was generated, e.g. 2026-06-12T01:04:42.763237+00:00.

Passive Liveness Face Search

⌘I