> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/shared-biometric-components/authenticate-facial.md).

# Facial Authentication

Service that performs facial validation between two faces, including both **open images** and **biometric templates**.

This service can be used to perform the following validations:

1. Facial authentication between two **open images**, whether or not they were generated by FacePhi Widgets.
2. Facial authentication between two **biometric templates**, requires integration of the FacePhi Selphi Mobile or Web Widget.
3. Facial authentication between an **open image** and a **biometric template**, requires integration of the FacePhi Selphi Mobile or Web Widget.
4. Facial authentication between the face in the **identity document photo (TokenFaceImage)** and an **open image**, requires integration of the FacePhi SelphID Mobile Widget.
5. Facial authentication between the face in the **identity document photo (TokenFaceImage)** and a **biometric template**, requires integration of the FacePhi Selphi Mobile and SelphID Mobile Widgets.

### Integration

* For **validation types 4 and 5**, implementation of the SelphID Mobile Widget is required to generate the **TokenFaceImage**.
* For **validation types 2, 3, and 5**, implementation of the Selphi Mobile or Web Widget is required to generate the **biometric template property (TemplateRaw)**.

### Endpoint

```
POST /services/authenticateFacial
```

### Headers

| Name          | Type   | Required | Description                                                |
| ------------- | ------ | -------- | ---------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | Authorization API key for access.                          |
| **family**    | string | No       | Value: **OnBoarding**. Required with the Tracking service. |

{% hint style="info" %}
All calls to the Tracking Endpoints with **Identity Platform** must include the `family`.
{% endhint %}

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type    | Required | Description                                                                                                                                                                                                             |
| ---------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token1`               | string  | **Yes**  | Image used as the **reference** for facial comparison. Depending on the method called, this may be the token generated by the SelphID Widgets (document photo token), an open image, or a tokenized biometric template. |
| `token2`               | string  | **Yes**  | Image used for the  **comparison**. It can be an open image or a tokenized biometric template.                                                                                                                          |
| `method`               | integer | **Yes**  | Indicates the  **comparison method** invoked. See  [Method specification](#especificación-de-método).                                                                                                                   |
| `tracking`             | object  | No       | Object representing the required tracking information.                                                                                                                                                                  |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform.                                                                                                                       |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                                                                                                                                                   |

#### Method specification

| Method | Description                                                                                                | Input                                       |
| ------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **1**  | Facial authentication using  **open images**                                                               | token1: Base64, token2: Base64              |
| **2**  | Facial authentication using  **biometric templates**                                                       | token1: templateRaw, token2: templateRaw    |
| **3**  | Facial authentication using an  **open image** and a  **biometric template**                               | token1: Base64, token2: templateRaw         |
| **4**  | Facial authentication using the  **token generated from the document photo crop** and an open image        | token1: tokenFaceImage, token2: Base64      |
| **5**  | Facial authentication using the  **token generated from the document photo crop** and a biometric template | token1: tokenFaceImage, token2: templateRaw |

#### Example Request

```json
{
  "token1": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "token2": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "method": 1,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** All Base64 images in the request count toward this limit together, with \~33% overhead compared to the original file (maximum of \~4.5 MB of original files in total). Compressed JPEG images of no more than 1–2 MB each are recommended. If the limit is exceeded, the gateway responds  `413` without processing the request. See  [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% endhint %}

### Responses

#### `200` Success

#### Response Parameters

| Parameter                           | Type    | Description                                                                                                                                 |
| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Code indicating the **overall result** of the service execution. See [Service Result Code](#service-result-code)                            |
| `serviceResultLog`                  | string  | Descriptive field for the service execution result. Includes details when an error or exception occurs in the module.                       |
| `serviceTime`                       | string  | Total processing time **(milliseconds)**.                                                                                                   |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                    |
| `serviceFacialAuthenticationHash`   | string  | Integrity hash of the biometric template used in a positive or uncertain facial authentication. **Only applicable to methods 2, 3, and 5.** |
| `serviceFacialAuthenticationResult` | integer | Code indicating the **facial matching result**. See [Service Facial Authentication Result](#service-facial-authentication-result)           |
| `serviceFacialSimilarityResult`     | number  | Value indicating the **facial similarity** between the face in the identity document photo and the selfie taken by the user. **1.0 = 100%** |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

| serviceResultCode | Description                                                                       | HTTP Code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 0                 | The service execution was successful; the module processed the request correctly. | 200       |

#### Service Facial Authentication Result

The `serviceFacialAuthenticationResult` indicates the result of the facial matching operations:

| Code | Result                           | Description                                                                                                                                                                                                         |
| ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | NONE                             | Facial verification could not be performed.                                                                                                                                                                         |
| 1    | NEGATIVE                         | The process completed successfully. The facial pattern comparison found no match between the faces.                                                                                                                 |
| 3    | POSITIVE                         | The process completed successfully. The facial pattern comparison found a match between the faces. The value of `serviceFacialSimilarityResult` indicates the percentage of similarity between the compared images. |
| 4    | NONE BECAUSE POSE EXCEED         | Facial verification could not be performed because of the face's pose.                                                                                                                                              |
| 5    | NONE BECAUSE INVALID EXTRACTIONS | Facial verification could not be performed because of problems extracting the facial pattern.                                                                                                                       |

#### Response example: Positive

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Positive",
  "serviceTime": "516",
  "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "serviceFacialAuthenticationHash": "47D0ACDCF08C348469C2F512BB59216B46DCD9B253822ED0E4EEAFCEB76AADD5AEF20CA31EC52D03EB290EBC91A6AD65FB0416F9EB2164D3854932153074289E",
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.99153554
}
```

#### Response example: Negative

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Negative",
  "serviceTime": "502",
  "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "serviceFacialAuthenticationHash": "09B9A4097E3642ADEDB665BA2E15B096FFB65A039E0D7137D0AD38666F90A010624C26867E6A7DB8346385610CC9FEDE435C3CC6A2AC9B008DD98C6EFE8C42E7",
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.01190000
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `413` Payload Too Large

The request exceeds the maximum allowed size. The gateway rejects it **without processing it**: the response does not include `serviceResultCode` or `serviceTransactionId`. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Request larger than 6 MB and up to 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Request larger than 10 MB (10,485,760 bytes) (`Content-Type: text; charset=utf-8`, plain text, not JSON):

```
HTTP content length exceeded 10485760 bytes.
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```
