> 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-fingerprint.md).

# Fingerprint Authentication

Service that performs **1:1 biometric fingerprint verification**, comparing a **probe** fingerprint against a **gallery** fingerprint from the same position. Each side can be provided as an **open/tokenized image** or as a **Biometric Template** previously extracted with [Fingerprint Extraction](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md), and the two formats can be combined.

### Endpoint

```
POST /services/authenticateFingerprint
```

### Headers

| Name          | Type   | Required | Description                                               |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | API Key for access authorization.                         |
| **family**    | string | No       | Value: **OnBoarding**. Required for the tracking service. |

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

### Request body

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

#### Parameters

| Parameter                                       | Type    | Required    | Description                                                                                                                                        |
| ----------------------------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `probe`                                         | array   | **Yes**     | Reference fingerprint. Must contain **exactly one** element.                                                                                       |
| `gallery`                                       | array   | **Yes**     | Comparison fingerprint. Must contain **exactly one** element, in the **same position** as the `probe`.                                             |
| `probe[].position` / `gallery[].position`       | integer | **Yes**     | Finger position according to NIST numbering (**1–10**). Must match between `probe` and `gallery`.                                                  |
| `probe[].tokenBuffer` / `gallery[].tokenBuffer` | string  | Conditional | Fingerprint image in **Base64** or a **Token** from FacePhi. Required if `template`is not sent. See [Accepted formats](#formatos-aceptados).       |
| `probe[].template` / `gallery[].template`       | string  | Conditional | Biometric Template (Base64) obtained from `extractFingerprint`. Required if `tokenBuffer`is not sent. See [Accepted formats](#formatos-aceptados). |
| `threshold`                                     | integer | No          | Decision threshold. If omitted, the tenant's value or the biometric engine's value is used.                                                        |
| `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.                                                                                              |

{% hint style="info" %}
The comparison method is automatically derived from the format of `probe` and `gallery` (image or template). See [Method specification](#especificación-de-método).
{% endhint %}

#### Accepted formats

* **Image** (`tokenBuffer`): Base64 of a fingerprint image in `WSQ`, `BMP`, `PNG`, `JPEG` or `JP2`, or a **token** from FacePhi.
* **Template** (`template`): the `template` in Base64 returned by [`extractFingerprint`](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md) (fingerprint already converted to a biometric template).
* **Encoding**: standard Base64, preferably **without line breaks**. If received wrapped (CRLF line breaks), the service normalizes it before processing.

#### Method specification

| Method | Description                                             | Input                              |
| ------ | ------------------------------------------------------- | ---------------------------------- |
| **1**  | Authentication using two **images**                     | probe: image, gallery: image       |
| **2**  | Authentication using two **biometric templates**        | probe: template, gallery: template |
| **3**  | Authentication using one **image** and one **template** | probe: image, gallery: template    |
| **4**  | Authentication using one **template** and one **image** | probe: template, gallery: image    |

#### Request example

```json
{
  "probe": [
    {
      "position": 2,
      "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo..."
    }
  ],
  "gallery": [
    {
      "position": 2,
      "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA..."
    }
  ],
  "threshold": 40,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** Fingerprint images and Base64 templates (`probe[].tokenBuffer`, `gallery[].tokenBuffer`, `probe[].template` and `gallery[].template`) count together toward this limit, with \~33% overhead compared to the original file (maximum \~4.5 MB of original files in total). Compressed formats such as `WSQ`, `JPEG` or `JP2`. 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.                                                               |
| `serviceTime`                  | string  | Total processing time **(milliseconds)**.                                                                         |
| `serviceTransactionId`         | string  | Transaction identifier associated with the request processed by the API.                                          |
| `serviceFingerprintAuthStatus` | string  | Matching result. See [Fingerprint Auth Status](#fingerprint-auth-status).                                         |
| `serviceFingerprintScore`      | number  | Similarity score between the two fingerprints being compared.                                                     |
| `serviceFingerprintThreshold`  | number  | Decision threshold applied in the comparison.                                                                     |

#### Service Result Code

| serviceResultCode | Description                                                                       | HTTP Code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 0                 | The service execution was successful; the module processed the request correctly. | 200       |
| -1                | The biometric engine could not complete the comparison (unprocessable input).     | 200       |

#### Fingerprint Auth Status

| Status     | Description                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `MATCH`    | The comparison is positive: the fingerprints match.                                                                         |
| `NO_MATCH` | The process completed successfully, but the fingerprints do not match.                                                      |
| `ERROR`    | The comparison could not be performed (for example, because the input was invalid or could not be processed by the engine). |

#### Response example: MATCH

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "match",
  "serviceTime": "318",
  "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "serviceFingerprintAuthStatus": "MATCH",
  "serviceFingerprintScore": 62.00000000,
  "serviceFingerprintThreshold": 40.00000000
}
```

#### Response example: NO\_MATCH

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "no_match",
  "serviceTime": "305",
  "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "serviceFingerprintAuthStatus": "NO_MATCH",
  "serviceFingerprintScore": 12.00000000,
  "serviceFingerprintThreshold": 40.00000000
}
```

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