> 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**, generated or not 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 present in the **photo of the Identity document (TokenFaceImage)** and a **open image**, requires integration of the FacePhi SelphID Mobile widget.
5. Facial authentication between the face present in the **photo of the Identity document (TokenFaceImage)** and a **biometric template**, requires integration of the FacePhi Selphi Mobile and SelphID Mobile widgets.

### Integration

* For the **validation types 4 and 5**, the implementation of the SelphID Mobile widget is required to generate the property **TokenFaceImage**.
* For the **validation types 2, 3 and 5**, the 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**  | Access authorization API Key.                              |
| **family**    | string | No       | Value: **Onboarding**. Required with the tracking service. |

{% hint style="info" %}
All calls to the Endpoints for tracking with **Identity Platform** must contain the header `family`.
{% endhint %}

### Request body

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

#### Parameters

| Parameter              | Type    | Required | Description                                                                                                                                                                                                        |
| ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `token1`               | string  | **Yes**  | Image used as **reference** for facial comparison. Depending on the invoked method, it 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 necessary tracking information.                                                                                                                                                            |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tokenized tracking information with the Platform.                                                                                                                  |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                                                                                                                                              |

#### Method Specification

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

#### Request example

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

### Responses

#### `200` Success

#### Response parameters

| Parameter                           | Type    | Description                                                                                                                                     |
| ----------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Code that indicates the **overall result** of the service execution. See [Service Result Code](#service-result-code)                            |
| `serviceResultLog`                  | string  | Descriptive field of the result of the service execution. Includes details when there is an error or exception 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 in methods 2, 3 and 5.**      |
| `serviceFacialAuthenticationResult` | integer | Code that indicates the **facial matching result**. See [Service Facial Authentication Result](#service-facial-authentication-result)           |
| `serviceFacialSimilarityResult`     | number  | Value that indicates 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 facial matching operations:

| Code | Result                           | Description                                                                                                                                                                                      |
| ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 0    | NONE                             | Facial verification could not be performed.                                                                                                                                                      |
| 1    | NEGATIVE                         | The process was executed correctly. The facial pattern comparison of the faces does not match.                                                                                                   |
| 3    | POSITIVE                         | The process was executed correctly. The facial pattern comparison of the faces is positive. The value of `serviceFacialSimilarityResult` indicates the % similarity between the compared images. |
| 4    | NONE BECAUSE POSE EXCEED         | Facial verification could not be performed due to the position of the face.                                                                                                                      |
| 5    | NONE BECAUSE INVALID EXTRACTIONS | Facial verification could not be performed due to problems in 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"
}
```

#### `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"
}
```