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

# Face Compare

> Compare two face images to determine if they belong to the same person.

## Overview

The face comparison endpoints let you determine whether two base64-encoded images contain the same person. An optional liveness check can confirm the second image is of a live person (not a photo of a photo).

***

## Face Compare

```
POST /Citizen/FaceCompare
```

Compares two face images and returns a match result with confidence score.

```bash theme={null}
curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/FaceCompare" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "Face1": "<base64_image_1>",
    "Face2": "<base64_image_2>",
    "CRef": "REF00001"
  }'
```

### Request Fields

| Field             | Type    | Required | Description                      |
| ----------------- | ------- | -------- | -------------------------------- |
| `ConsentReceived` | boolean | **Yes**  | Must be `true`                   |
| `Face1`           | string  | **Yes**  | Base64-encoded first face image  |
| `Face2`           | string  | **Yes**  | Base64-encoded second face image |
| `CRef`            | string  | No       | Your transaction reference       |

### Response

```json theme={null}
{
  "isIdentical": true,
  "confidence": 0.98,
  "Status": "Success",
  "CRef": "REF00001"
}
```

| Field         | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `isIdentical` | `true` if the two faces are determined to be the same person  |
| `confidence`  | Confidence score of the match (0–1, higher is more confident) |

***

## Face Compare with Liveness

```
POST /Citizen/FaceCompareWithLiveness
```

Compares two face images **and** runs a liveness check on the second image to confirm it is a live capture.

```bash theme={null}
curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/FaceCompareWithLiveness" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "Face1": "<base64_image_1>",
    "Face2": "<base64_selfie_with_liveness_data>",
    "CRef": "REF00001"
  }'
```

### Response

```json theme={null}
{
  "isIdentical": true,
  "confidence": 0.98,
  "LivenessResult": {
    "LivenessResultScore": 1,
    "LivenessResultProbability": 0.85,
    "LivenessResultQuality": 0.9,
    "LivenessResultClass": false,
    "LivenessPassResult": true,
    "LivenessMessage": "Liveness check successful"
  },
  "Status": "Success",
  "CRef": "REF00001"
}
```

### Liveness Result Fields

| Field                       | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `LivenessResultScore`       | Overall liveness score                                |
| `LivenessResultProbability` | Probability the image is of a live person (0–1)       |
| `LivenessResultQuality`     | Quality score of the liveness capture (0–1)           |
| `LivenessResultClass`       | `false` = live (real person), `true` = spoof detected |
| `LivenessPassResult`        | `true` if the liveness check passed                   |
| `LivenessMessage`           | Human-readable result message                         |

<Note>
  `LivenessResultClass: false` means the image is classified as a **real live person**, this is the desired passing
  state. A value of `true` indicates a potential spoof attempt.
</Note>