> For the complete documentation index, see [llms.txt](https://docs.complycube.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.complycube.com/documentation/api-reference/check-types/face-authentication-check.md).

# Face Authentication Check

Face Authentication Check API for KYC face matching, biometric verification, liveness checks, and returning user authentication.

## Run a face authentication check

To run a Face Authentication Check, you must [create a check ](/documentation/api-reference/core-resources/checks/create-a-check.md)with `type` set to `face_authentication_check`.

This check can only be performed on a [client](/documentation/api-reference/core-resources/clients.md) of type `person`. Furthermore, the provided client must have been enrolled previously.

[Learn more about Face Authentication Checks](/documentation/product-guides/biometric-and-liveness-verification/face-authentication-check.md).

{% hint style="info" %}
Get in touch with your Account Manager or [contact us](https://www.complycube.com/sales) to enable this service.
{% endhint %}

## Check request

<table><thead><tr><th width="241">Attribute</th><th width="96.4">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>clientId</code></td><td>string</td><td>The ID of the client associated with this check. (<strong>Required</strong>)</td></tr><tr><td><code>type</code></td><td>string</td><td>This must be set to <code>face_authentication_check</code>. (<strong>Required</strong>)</td></tr><tr><td><code>livePhotoId</code></td><td>string</td><td>The ID of the live photo. (<strong>Required</strong>)</td></tr></tbody></table>

### Example request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "livePhotoId":"LIVE_PHOTO_ID",
          "type": "face_authentication_check"
        }'
```

{% endtab %}

{% tab title="Node.js" %}

```json
const check = await complycube.check.create("CLIENT_ID", {
        livePhotoId: "LIVE_PHOTO_ID",
        type: "face_authentication_check"
});
```

{% endtab %}

{% tab title="Python" %}

```python
check = cc_api.check.create(
    'CLIENT_ID',
    'face_authentication_check', 
    livePhotoId='LIVE_PHOTO_ID'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'face_authentication_check',
        'livePhotoId' => 'LIVE_PHOTO_ID'
    ]
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  livePhotoId = "LIVE_PHOTO_ID",
  type = "face_authentication_check"
};

var check = await checkApi.CreateAsync(checkRequest);
```

{% endtab %}
{% endtabs %}

## Result object

The `result` object is only returned when the status of the check is `complete` . It has two components - `outcome` and `breakdown`.

### Outcome

The outcome attribute represents the overall check result. Returned values include:

1. `clear`: Indicates the face on the provided live photo matches one of the client's previously enrolled faces, and hence the client's face authentication is successful.
2. `attention`: Indicates the face on the live photo does not match any of the client's previously enrolled faces, hence requiring attention.

### Breakdown

The breakdown comprises the following objects:

#### `faceAuthentication` object

The face authentication results. It has the following constituents:

* `facialSimilarity`: Indicates whether the face on the live photo matches a client's enrolled face.
* `breakdown`: Breakdown related to face authentication.
  * `facesMatched`: If the live photo matches an enrolled face, this attribute will be returned. It contains the following:
    * `livePhotoId`: The ID of the live photo corresponding to the enrolled face that matched.
    * `liveVideoId`: The ID of the live video corresponding to the enrolled face that matched.
    * `facialSimilarityScore`: Indicates the similarity level of the face on the live photo provided against the enrolled face. The score will be 100 for a perfect match.
  * `enrolledFaces`: This contains details about previously enrolled faces for a given client. It comprises of the following:
    * `livePhotoIds`: An array of live photo IDs used for enrolling the client's face.
    * `liveVideoIds`: An array of live video IDs used for enrolling the client's face.

## Sample Response

```javascript
{
    "id": "6231d54079f59b1530fc76e3",
    "entityName": "John Doe",
    "type": "face_authentication_check",
    "clientId": "6230d4ab58ed4a434afbf2cc",
    "livePhotoId": "6231d137095afa000955ffc2",
    "status": "complete",
    "result": {
        "outcome": "clear",
        "breakdown": {
            "faceAuthentication": {
                "facialSimilarity": "clear",
                "breakdown": {
                    "facesMatched": [
                        {
                            "livePhotoId": "6230d4f928e6ae00091747f9",
                            "facialSimilarityScore": 100
                        }
                    ],
                    "enrolledFaces": {
                        "livePhotoIds": [
                            "6230d4f928e6ae00091747f9",
                            "6230d4f928e6ae00091747fa"
                        ]
                    }
                }
            }
        }
    },
    "updatedAt": "2022-03-01T12:17:06.046Z",
    "createdAt": "2022-03-01T12:17:04.809Z"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.complycube.com/documentation/api-reference/check-types/face-authentication-check.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.