# Perform a Likeness (Face Similarity) Check

`POST /likeness_check`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/likeness_check`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/likeness_check`

Compares two face images (an ID/document or reference image and a probe/selfie image) and returns a
similarity score together with a threshold evaluation flag (`biometric_passed`). The service is intended
for validating whether the two supplied images likely represent the same individual.

## Inputs

Provide both images as Base64 **data URI** strings (recommended form: `data:image/jpeg;base64,/9j/4AA...`) or
raw base64 without a prefix. Supported formats are JPEG and PNG. Maximum file size per image is 5 MB.

An optional `similarity_threshold` (0-100) can be supplied to override the system default.
If omitted, the configured default threshold is used when determining `biometric_passed`.

## Similarity & Threshold

The underlying biometric engine returns a `similarity` value (floating point). The request (or default)
threshold is applied: `biometric_passed = similarity >= threshold`.

## Typical Use Case

1. Capture / obtain an authoritative reference photo (e.g. ID document portrait).
2. Capture a live probe (selfie) image from the user.
3. Submit both images to this endpoint.
4. Use the `biometric_passed` boolean (and raw similarity) to decide downstream workflow steps.

## Error Handling

Validation and processing issues return HTTP 400 with a descriptive `message`.
If multiple validation errors are present, the API returns the **first** validation message.
Face comparison engine errors (for example `no_face_found`) are also returned as HTTP 400 messages.

## Request body

Two face images (reference & probe) and an optional threshold override.

| Field | Type | Description |
|-------|------|-------------|
| `photo` | string | **Required.** Base64 (optionally data URI) reference image (e.g. ID/document portrait). JPEG or PNG. Max 5 MB. Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...` |
| `probe_image` | string | **Required.** Base64 (optionally data URI) probe / selfie image to compare against the reference. JPEG or PNG. Max 5 MB. Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...` |
| `similarity_threshold` | number (float) [0..100] | Optional override threshold (0-100). If omitted, system default is used. Example: `80` |

**Sample request**

```json
{
    "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "probe_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "similarity_threshold": 80
}
```

## Responses

### 200 Likeness comparison completed successfully

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` on success. Example: `Ok` |
| `api_reference` | string (uuid) | Unique audit reference for this API call. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `result` | object | Likeness comparison result object. |
| `result.similarity` | number (float) | Biometric engine similarity score (higher means more similar). Example: `95.5` |
| `result.threshold` | number (float) | Threshold used to evaluate pass/fail (request value or system default). Example: `80` |
| `result.biometric_passed` | boolean | True if `similarity >= threshold`. Example: `true` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "result": {
        "similarity": 95.5,
        "threshold": 80,
        "biometric_passed": true
    }
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))