1:1 face matching, 1:N search, registration, and liveness detection

Face Biometrics

The face API provides biometric operations: 1:1 verification (does this face match this identity?), 1:N search (who is this person?), face registration into indexed databases, and liveness/quality analysis. All endpoints accept base64-encoded images.

Databases

9thSense ships with 6 pre-built face index databases:

Database IDDescription
politically_exposed_personPEP watchlist
sanction_watchSanctions and embargoes list
public_figuresPublic figures for identity disambiguation
fraudstersKnown fraud actors
celebrityCelebrity recognition index
customTenant-specific registries populated via /face/register

Additional custom databases can be provisioned on request.

Endpoints

1:1 Face Match

POST /api/v1/face/match

Compares two faces and returns a similarity score and match verdict.

Request body:

sourceobjectrequired

Reference face image. { "data": "<base64>", "mime_type": "image/jpeg" }.

targetobjectrequired

Face to compare against. Same format as source.

thresholdnumber

Minimum similarity score to consider a match (0–1). Default 0.75.

tenant_idstring

Response (200):

matchboolean
Whether the faces are considered the same person.
similaritynumber
Cosine similarity score (0–1). Higher is more similar.
source_qualitynumber
Face quality score of the source image (0–1).
target_qualitynumber
Face quality score of the target image (0–1).
processing_msnumber
Time taken in milliseconds.

Example response:

{
  "match": true,
  "similarity": 0.934,
  "source_quality": 0.91,
  "target_quality": 0.87,
  "processing_ms": 145
}

1:N Face Search

POST /api/v1/face/search

Searches one or more databases for faces matching the probe image. Returns the top-N matches.

Request body:

probeobjectrequired

Probe face image. { "data": "<base64>", "mime_type": "image/jpeg" }.

databasesstring[]required

List of database IDs to search (e.g. ["politically_exposed_person", "sanction_watch"]).

top_knumber

Number of top matches to return per database. Default 5.

thresholdnumber

Minimum similarity score to include in results. Default 0.70.

tenant_idstring

Response (200):

resultsobject[]

Array of match objects, sorted by similarity descending.

Match Object
databasestring
Database where this match was found.
face_idstring
Registered face ID.
similaritynumber
Similarity score (0–1).
metadataobject
Metadata stored with this registration (name, ID, tags, etc.).
searched_databasesstring[]
List of databases that were searched.
processing_msnumber

Example response:

{
  "results": [
    {
      "database": "politically_exposed_person",
      "face_id": "pep_00123",
      "similarity": 0.912,
      "metadata": { "name": "John Doe", "country": "IN", "category": "domestic_politician" }
    }
  ],
  "searched_databases": ["politically_exposed_person", "sanction_watch"],
  "processing_ms": 210
}

Register Face

POST /api/v1/face/register

Registers a face into one of the indexed databases. The face embedding is computed and stored for future 1:N searches.

Request body:

imageobjectrequired

Face image to register. { "data": "<base64>", "mime_type": "image/jpeg" }.

databasestringrequired

Target database ID (e.g. "employee").

face_idstring

Optional external ID. Auto-generated UUID if not provided.

metadataobject

Arbitrary metadata to store with this registration (name, employee ID, tags, etc.).

tenant_idstring

Response (200):

face_idstring
The registered face ID.
databasestring
Database the face was added to.
qualitynumber
Face quality score (0–1). Low-quality faces may be rejected.
registered_atstring
ISO 8601 timestamp.

Extract / Liveness Analysis

POST /api/v1/face/extract

Analyzes a face image for quality, liveness, and biometric attributes. Does not perform matching or registration.

Request body:

imageobjectrequired

Face image. { "data": "<base64>", "mime_type": "image/jpeg" }.

checksstring[]

Specific checks to run. Default: all. Options: "liveness", "quality", "attributes", "spoof".

tenant_idstring

Response (200):

face_detectedboolean
Whether a face was found in the image.
face_countnumber
Number of faces detected.
qualitynumber
Overall face quality score (0–1).
livenessobject

Liveness check result.

Liveness
is_liveboolean
Whether the face is determined to be live (not a photo/print).
scorenumber
Liveness confidence (0–1).
spoof_typestring
If detected: "print", "screen", "mask", or null.
attributesobject
Estimated attributes (age range, pose angles, occlusion).
processing_msnumber

Bulk Search (Async)

POST /api/v1/face/bulk/search

Asynchronous bulk 1:N search for large volumes of probe images. Enqueues a batch job and returns a job ID to poll.

Request body:

probesobject[]required

Array of probe images. Each: { "data": "<base64>", "mime_type": "image/jpeg", "id": "<your-ref-id>" }.

databasesstring[]required

Databases to search.

thresholdnumber

Minimum similarity threshold. Default 0.70.

webhook_urlstring

URL to POST results to when the batch completes.

tenant_idstring

Response (202):

job_idstring
Bulk search job ID.
statusstring
"queued"
probe_countnumber
Number of probes enqueued.

List Face Indices

GET /api/v1/face/index/details

Returns details about all accessible face index databases.

Query parameters:

tenant_idstring

Response (200): Array of index detail objects.

databasestring
Database ID.
display_namestring
Human-readable name.
face_countnumber
Number of registered faces.
last_updatedstring
ISO 8601 timestamp of last registration.

Recent Registrations

GET /api/v1/face/recent/registered

Returns recently registered faces across all databases.

Query parameters:

databasestring

Filter to a specific database.

limitnumber

Number of records to return. Default 20.

tenant_idstring

Response (200): Array of registration summary objects.

face_idstring
databasestring
metadataobject
qualitynumber
registered_atstring
PreviousAnalyticsNextOverview