Get started

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.

---