FaceMatch - Sense

Face Match Overview

The Face Verification API is a high-level, commercial-grade system designed to verify if two images (typically an ID document and a selfie) contain the same person's face. It leverages advanced face detection, recognition, and image enhancement techniques to ensure robust performance across various image qualities and document types. The API is built using FastAPI, a modern Python web framework, and supports multiple face detection and recognition backends for flexibility and accuracy.

This document provides a detailed technical overview of the system, including its architecture, dependencies, API endpoints, and implementation details.

Follow these steps

Follow the Authentication steps - click here

Face Match API

Verifies whether the faces in two uploaded images (typically an ID document and a selfie) match.

End point:

Request

Method:POST
Content-Type:application/json

Authorization :

Format: Authorization: Bearer <token>

Parameters:

document_image (file): Image of the ID document (e.g., passport, driver's license).M
selfie_image (file): Selfie or comparison photo.M
unique_id : reference id for your system reference. (e.g., USER0001) -OP
document_type (form, optional): Type of ID document (passport, national_id, drivers_license, voter_id, pan_card, aadhaar, unknown).Default: unknown.-OP

HINT:

M = Mandatory
OP = Optional

Response

Status Code: 200 OK
Data
1. reference_id - For your reference

Example Request

curl --location 'https://strctluat.gosense.ai/api/v1/sense/face-match'
--header 'Authorization: ••••••'
--header 'Content-Type: application/json'
--data '{
   "unique_id" : "USER123",
   "document_image" : "document_image_url",
   "selfie_image" : "selfie_image_url",
   "document_type" : "passport"
}

{
            "success": true,
            "message": "Facematch info recorded successfully",
            "code": 8028,
            "data": {
                    "reference_id": "181acdac-6817-4540-b1a7-399e79cd346b",
                    "status": "pending"
            }
    }

Face Match - Status check and Details API

The face-match model runs and generates a result. This API provides both detailed information and status updates

End point:

Authorization :

Format: Authorization: Bearer <token>

Content-Type :application/json

Parameters:

reference_id : A unique reference ID will be generated upon accepting the POST request.M

Response

Status Code: 200 OK

{
       "success": true,
       "message": "Facmatch info",
       "code": 8033,
       "data": {
            "reference_id": "0fbd661c-d5b6-429f-89ac-4381f351823c",
            "unique_id": "USER123",
            "selfie_image":  “<selfie_image_url>",
    	      "document_image": "<document_image_url>",
    	      "document_type": "passport",
    	      "status": "completed",
    	      "createdAt": "2025-06-11T10:29:50.521Z",
            "completed_at": "2025-06-16T10:24:04.979Z",
     	  "response": {
   		  "verified": true,
    		"distance": 0.2705468684434891,
    		"confidence": 22.700894730431685,
    		"threshold": 0.35,
    		"api_version": "1.0.0",
    		"processing_time": 4.289268255233765
 	 	}
}
  }

Webhook Configuration
1. Webhook Configuration Guide
  This paragraph explains how to configure a webhook to receive automated callbacks from the Face Match API when a match result becomes available. Your system should expose an HTTPS endpoint that can receive POST requests. The API will send a payload to the configured webhook URL once processing is complete.
2. Webhook Registration
  Webhook registration refers to the process of configuring your webhook endpoint in the system panel. This setup allows the Face Match API to automatically send a callback to your specified URL once the face match process is complete.
  Note: Webhook configuration must be completed in the panel before initiating the face match request.
3. Webhook Fields:
  1. API : The complete URL to which the system will send the face match POST callbacks.
  2. Username : The Basic Auth username for securing the webhook endpoint.
  3. Password : The Basic Auth password associated with the username.
  4. Enable/Disable Option: You can enable or disable he webhook integration anytime via the panel.