> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynopsis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```bash theme={null}
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:

```json theme={null}
{
  "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.

***