Face Search

The Veriguard biometric service exposes face operations under /api/v1/face. All endpoints accept multipart/form-data.

1:1 Face match

Compare two face images and receive a similarity score and match decision.

POST /api/v1/face/match
Content-Type: multipart/form-data

Response

{
  "confidence": 0.97,
  "matchResult": "MATCH",
  "similarityScore": "0.97"
}

matchResult is either MATCH or NO_MATCH. confidence and similarityScore are in the range [0, 1].

cURL example

curl -X POST https://api.9thsense.ai/api/v1/face/match \
  -H "Authorization: Bearer $TOKEN" \
  -F "source_image=@passport_photo.jpg" \
  -F "target_image=@selfie.jpg"

Python example

import httpx

with httpx.Client(base_url="https://api.9thsense.ai") as client:
    resp = client.post(
        "/api/v1/face/match",
        headers={"Authorization": f"Bearer {token}"},
        files={
            "source_image": ("passport.jpg", open("passport.jpg", "rb"), "image/jpeg"),
            "target_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg"),
        },
    )
    match = resp.json()
    print(match["matchResult"], match["confidence"])

1:N Face search

Search a probe face against one or more of the platform's biometric databases and return the closest matches.

POST /api/v1/face/search
Content-Type: multipart/form-data

Response

{
  "success": true,
  "message": "Search complete",
  "searchId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "matches": [
    {
      "faceId": "abc123",
      "name": "John Doe",
      "dob": "1980-05-14",
      "nationality": "US",
      "faceDatabaseType": "PEP",
      "confidence": 0.94,
      "image": "<base64>",
      "metadata": "{...}"
    }
  ]
}

Each match carries a faceDatabaseType field indicating which database it came from.

Biometric databases

The platform ships with six named databases. Pass one or more target_index_ids to restrict the search scope.

Bulk search

For batch processing, submit a single probe image and receive asynchronous search results across all indexes:

POST /api/v1/face/bulk/search
Content-Type: multipart/form-data

Accepts the same fields as /search. Returns a list of PipelineRequest objects, one per submitted search job.

Face registration

Register a face into one or more indexes so it can be matched in future searches.

POST /api/v1/face/register
Content-Type: multipart/form-data

Response

{
  "requestId": "req_abc123",
  "registeredIds": ["idx_001", "idx_002"],
  "name": "Jane Smith",
  "idNo": "AB1234567",
  "dob": "1990-11-30",
  "nationality": "IN"
}

Biometric analysis (liveness + quality)

Extract a full biometric profile from a face image. This endpoint runs all enabled check groups — detection, quality, pose/expression, integrity, compliance, and demographics.

POST /api/v1/face/extract

Response structure

{
  "success": true,
  "profile": "COMPLIANT",
  "overallPassed": true,
  "checkGroups": {
    "detectionChecks": {
      "result": "PASS",
      "checks": [{"type": "FACE_DETECTED", "result": "pass", "score": 0.99}]
    },
    "qualityChecks": {
      "result": "PASS",
      "checks": [
        {"type": "BLUR", "result": "pass", "score": 0.92},
        {"type": "BRIGHTNESS", "result": "pass", "score": 0.88}
      ]
    },
    "integrityChecks": {
      "result": "PASS",
      "checks": [
        {"type": "DEEPFAKE", "result": "pass", "score": 0.01},
        {"type": "SYNTHETIC", "result": "pass", "score": 0.02}
      ]
    },
    "poseExpressionChecks": {"result": "PASS", "checks": []},
    "complianceChecks": {"result": "PASS", "checks": []},
    "demographicChecks": {"result": "PASS", "checks": []}
  }
}

The integrityChecks group runs deepfake and synthetic-face detection. A low score for DEEPFAKE means the image is likely authentic. The debug field (omitted above) carries raw model scores when debug mode is enabled.

Index metadata

Retrieve metadata about available face indexes for a given action type:

GET /api/v1/face/index/details?action_type=FACE_SEARCH
GET /api/v1/face/index/details/{id}

Valid action_type values are EXTRACTION, VERIFICATION, FACE_EXTRACTION, FACE_MATCH, FACE_INDEXING, FACE_SEARCH, LIVENESS.

Recently registered faces

GET /api/v1/face/recent/registered?limit=10&offset=0

Returns the most recently enrolled faces for the authenticated tenant.