cURL

curl -X POST 'https://verification.didit.me/v3/face-search/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'search_type=most_similar' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [
            40,
            40,
            120,
            120
          ],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": null
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

Biometrics & Face

Face Search

Search a face image (1:N) against your application’s face search index — faces enrolled from verification sessions, saved standalone API calls, direct user-profile face uploads, and your block/allow lists — and get back ranked similarity matches plus blocklist and duplicate warnings.

How it works. The largest detected face in user_image is embedded and searched against the index, scoped to your application. Up to 5 matches above the similarity floor are returned in matches, each with similarity_percentage, the originating session (session_id, session_number, status, vendor_data), user_details extracted during that session’s document verification, is_blocklisted / is_allowlisted flags, and a source discriminator (session, imported, or list_entry).

search_type=most_similar (default) ranks every enrolled face by similarity — use it for deduplication and fraud-ring investigation.
search_type=blocklisted_or_approved restricts candidates to blocklisted faces, allowlisted faces, faces from approved sessions, and imported user-profile faces, ranking blocklisted entries first — use it when the primary goal is blocklist screening.

status is Declined only when a FACE_IN_BLOCKLIST or POSSIBLE_FACE_IN_BLOCKLIST warning fires; DUPLICATED_FACE / POSSIBLE_DUPLICATED_FACE (information) and MULTIPLE_FACES_DETECTED (warning) never decline. Unlike Passive Liveness, this endpoint does not exclude prior sessions with the same vendor_data from matching. A passive-liveness analysis also runs internally and is stored with the persisted session, but its result is not part of this response.

Billing. Each 200 response consumes one Face Search API credit (standalone APIs have no free tier). Insufficient balance returns 403 before any image processing.

Session persistence and face enrollment (save_api_request, default true). When true, the call is persisted as an API-type session (Business Console, GET /v3/session/{sessionId}/decision/ via the returned request_id, status.updated webhook) and the searched face is enrolled into your face search index. Faces enrolled by Face Search calls are excluded from future Face Search results, so repeated searches never match each other. When false, the call is one-shot: nothing is stored, the face is not enrolled, and match_image_url values are internal storage paths rather than downloadable URLs.

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-search

cURL

curl -X POST 'https://verification.didit.me/v3/face-search/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'search_type=most_similar' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [
            40,
            40,
            120,
            120
          ],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": null
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "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

Front-facing face image to search with. 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. The image must contain at least one detectable face — otherwise the endpoint returns 400. When several faces are present, the largest one is searched and a MULTIPLE_FACES_DETECTED warning is added.

search_type

enum<string>

default:most_similar

Search policy. most_similar (default) ranks every enrolled face in your application by similarity. blocklisted_or_approved restricts candidates to blocklisted faces, allowlisted faces, faces from approved sessions, and imported user-profile faces — with blocklisted entries ranked first.

Available options:

most_similar,

blocklisted_or_approved

Example:

"most_similar"

rotate_image

boolean

default:false

When true, the service tries 90-degree rotations of the input and uses the orientation that yields the best face detection. Useful when EXIF orientation is missing. Adds latency.

Example:

false

save_api_request

boolean

default:true

When true (default), persists the call as an API-type session, emits a status.updated webhook, presigns match_image_url values, and enrolls the searched face into your face search index (Face Search enrollments are excluded from future searches). When false, the search is one-shot — no session is stored and the face is not enrolled.

Example:

true

vendor_data

string

Optional opaque identifier (your user id, email, UUID…) stored on the persisted session and echoed back. It does not exclude same-user faces from the search results.

Example:

"user-123"

metadata

object

Optional JSON object stored with the session (when save_api_request=true) and echoed back. In multipart requests, send it as a JSON-encoded string field — it is parsed into an object.

Example:

{ "flow": "dedup_check" }

Response

Face search completed. face_search.matches holds up to 5 similar faces ordered by similarity; an empty array means no enrolled face exceeded the similarity floor. status is Declined only on blocklist hits — duplicate matches alone return Approved, so inspect matches and warnings, not just status. 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_search

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.

Face Match Age Estimation API

⌘I