Skip to main content

​
Face Comparison API - Getting Started

This guide explains how to perform face comparison using the /service/facecompare API endpoint.

​
Example Request

The following example demonstrates how to call the Face Compare API using curl: 
curl --location '/service/facecompare' \
  --header 'X-Domain-Id: <your-domain-id>' \
  --form 'file0=@"/Users/ryan/Documents/cynopsis/USPP2.jpg"' \
  --form 'file1=@"/Users/ryan/Documents/cynopsis/selfie1.jpeg"'
  • file0: The first image (e.g., a photo from a document).
  • file1: The second image (e.g., a selfie taken by the user).
  • X-Domain-Id: (Required) Your assigned domain identifier.
Ensure both files are valid image formats and that you have provided your correct domain ID header.

​
Example Response

A sample response from the API would look like: 
{
  "id": "cde55a87-88e5-4484-90d3-8b13eef8c04f",
  "status": "MATCHED/NOT MATCHED/UNCERTAIN/ERROR",
  "status_task": "SUCCESS/FAILURE",
  "result": {
    "simiarity": "string",
    "matched": true,
    "error": "string"
  },
  "error": "string"
}

​
Response Fields

  • id: Unique identifier for this face comparison task.
  • status: Indicates the face comparison result. Possible values:
    • MATCHED: The faces are considered a match.
    • NOT MATCHED: The faces do not match.
    • UNCERTAIN: The result is unclear (e.g., poor image quality).
    • ERROR: An error occurred during comparison.
  • status_task: Processing status - either SUCCESS or FAILURE.
  • result:
    • simiarity: The similarity score returned as a string (expected to be a number/percentage as string).
    • matched: Boolean indicating if the comparison was a definite match (true) or not (false).
    • error: If any occurred, error details.
  • error: Any error message at the top level.

​
Face Comparison & Similarity Logic

The similarity score helps to quantify how closely the two faces match:
  • If similarity is 100%, the system interprets this as potential duplication (e.g., both images are exactly the same), and matched will be false to prevent fraud or duplicate faces.
  • A similarity in the 30%-70% range is generally considered uncertain and may result in an UNCERTAIN status.
  • In real use, most matched faces return a similarity of 80-99%.
  • The matched boolean is set to true if the faces are recognized as belonging to the same person (within the accepted, practical similarity range).
  • The similarity value is also provided to allow clients to apply custom thresholds or logic for their specific requirements.
Note: The precise cut-off logic may be tuned by your organization’s policies. Consult the technical team or support if you wish to customize the acceptance threshold.