> 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 the **Biometric Verification of Fingerprint 1:1**, comparing a fingerprint from **probe** against a fingerprint from **gallery** of the same position. Each side can be provided as **open/tokenized image** or as **Biometric Template** previously extracted with [Fingerprint Extraction](/docs.facephi-en/rest-api/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md), allowing a combination of both formats.

### Endpoint

```
POST /services/authenticateFingerprint
```

### 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                                                                                                                                      |
| ----------------------------------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `probe`                                         | array   | **Yes**     | Reference fingerprint. Must contain **exactly one** element.                                                                                     |
| `gallery`                                       | array   | **Yes**     | Comparison fingerprint. Must contain **exactly one** element, from 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 not sent `template`. See [Accepted formats](#formatos-aceptados).       |
| `probe[].template` / `gallery[].template`       | string  | Conditional | Biometric Template (Base64) obtained from `extractFingerprint`. Required if not sent `tokenBuffer`. 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. It contains tokenized tracking information with the Platform.                                             |
| `tracking.operationId`                          | string  | No          | Operation identifier generated by the SDK Mobile/Web.                                                                                            |

{% hint style="info" %}
The comparison method is derived automatically 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`](/docs.facephi-en/rest-api/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md) (fingerprint already converted to Biometric Template).
* **Encoding**: standard base64, preferably **without line breaks**. If it arrives "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 a **template** | probe: image, gallery: template    |
| **4**  | Authentication using one **template** and a **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"
  }
}
```

### 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 for the result of the service execution.                                                            |
| `serviceTime`                  | string  | Total processing time **(milliseconds)**.                                                                             |
| `serviceTransactionId`         | string  | Transaction identifier associated with the request processed by the API.                                              |
| `serviceFingerprintAuthStatus` | string  | Match result. See [Fingerprint Auth Status](#fingerprint-auth-status).                                                |
| `serviceFingerprintScore`      | number  | Similarity score between the two fingerprints 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, invalid input or input that cannot 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"
}
```

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