Face Search (1:N)

Search a submitted face image against one or more indexed face databases. Returns a ranked list of matches. This is a synchronous endpoint.

Endpoints

Get Available Databases

GET{BASE_URL}/face/index/details?action_type=FACE_SEARCH

Returns the list of face databases available for searching. Use the id field from this response as the target_index_ids when submitting a search.

Database Response Fields

Field	Type	Required	Description
id	String	No	Unique identifier of the face index database
index_name	String	No	Human-readable name of the database
index_type	String	No	Type of index — INTERNAL or EXTERNAL
record_count	Number	No	Total number of face records in this database
title	String	No	Display title of the database
description	String	No	Description of what the database contains

Submit Face Search

POST{BASE_URL}/face/search?perform_liveness_check=true

Request Parameters

Field	Type	Required	Description
source_image	File	Yes	The face image to search for
target_index_ids	String	Yes	Comma-separated list of face database IDs to search against
min_match_score	Number	No	Minimum match score threshold (0–100). Defaults to 70
max_results	Number	No	Maximum number of matches to return. Defaults to 5

Query Parameters

Parameter	Type	Required	Description
perform_liveness_check	Boolean	No	Whether to run liveness detection on the source image. Defaults to true

Sample Request

bash

curl '{BASE_URL}/face/search?perform_liveness_check=true' \
-H 'Authorization: Basic <base64_encoded_credentials>' \
-H 'Content-Type: multipart/form-data' \
-F 'source_image=@FACE_IMAGE_PATH' \
-F 'target_index_ids=<INDEX_ID_1>,<INDEX_ID_2>' \
-F 'min_match_score=70' \
-F 'max_results=5'

Response

json

{
"response": [
  {
    "match_score": 94.2,
    "distance": 0.058,
    "match_image_id": "<IMAGE_ID>",
    "name": "John Doe",
    "dob": "1990-01-15",
    "nationality": "IN",
    "gender": "M",
    "id_no": "<ID_NUMBER>",
    "address": "<ADDRESS>",
    "watch_list": [],
    "additional_info": "",
    "index_name": "<INDEX_NAME>",
    "index_type": "INTERNAL"
  }
]
}

Match Result Fields

Field	Type	Required	Description
match_score	Number	No	Similarity score for this match (0–100). Higher is more similar
distance	Number	No	Feature vector distance from the source. Lower means closer match
match_image_id	String	No	ID of the matched face image — use with the media download endpoint to retrieve it
name	String	No	Name associated with the matched record
index_name	String	No	Name of the database the match was found in
index_type	String	No	Type of the database — INTERNAL or EXTERNAL
watch_list	String	No	Array of watchlist categories this record belongs to, if any

Download Matched Face Image

GET{BASE_URL}/media/file/download/{file_id}

Use the match_image_id from a face search result to fetch the corresponding face image as base64.

json

{
"response": {
  "file_base64": "<BASE64_IMAGE_DATA>",
  "file_name": "face_image.jpg",
  "file_type": "image/jpeg",
  "file_id": "<FILE_ID>"
}
}