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

# Fingerprint Extraction

Service that performs the **capture and extraction of fingerprint biometric templates** from open or tokenized fingerprint images. Each image is converted into a reusable template (`template`) for the fingerprint authentication service.

{% hint style="warning" %}
Please note that the returned quality values are estimates based on the provided fingerprint image. Actual accuracy and reliability may vary depending on the quality and characteristics of the input image.
{% endhint %}

### Endpoint

```
POST /services/extractFingerprint
```

### 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. |

### Request body

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

#### Parameters

| Parameter               | Type    | Required | Description                                                                                                           |
| ----------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `fingers`               | array   | **Yes**  | List of fingerprints to process. From **1 to 10** fingerprints per request are supported (configurable per tenant).   |
| `fingers[].position`    | integer | **Yes**  | Finger position according to NIST numbering (**1–10**). See [Finger Positions](#posiciones-de-dedo).                  |
| `fingers[].tokenBuffer` | string  | **Yes**  | Fingerprint image in **Base64** or a **Token** from FacePhi. See [Accepted Formats](#formatos-aceptados-tokenbuffer). |
| `fingers[].dpi`         | integer | No       | Image resolution in dots per inch. If omitted, the tenant's default value (500) is used.                              |
| `fingers[].scanType`    | string  | No       | Capture type (`Plain` by default). See [Capture Types](#tipos-de-captura-scantype).                                   |

#### Finger Positions

| Position | Finger      | Position | Finger     |
| -------- | ----------- | -------- | ---------- |
| 1        | RightThumb  | 6        | LeftThumb  |
| 2        | RightIndex  | 7        | LeftIndex  |
| 3        | RightMiddle | 8        | LeftMiddle |
| 4        | RightRing   | 9        | LeftRing   |
| 5        | RightLittle | 10       | LeftLittle |

#### Accepted Formats (tokenBuffer)

The `tokenBuffer` field accepts a fingerprint image encoded in **Base64**, or a **Token** from FacePhi (a tokenized reference that the service resolves internally).

Image formats supported by the engine:

| Format | Description                                                                           |
| ------ | ------------------------------------------------------------------------------------- |
| `WSQ`  | Wavelet Scalar Quantization (fingerprint standard; common format for capture widgets) |
| `BMP`  | Bitmap                                                                                |
| `PNG`  | Portable Network Graphics                                                             |
| `JPEG` | JPEG                                                                                  |
| `JP2`  | JPEG 2000 (container `.jp2` or codestream)                                            |

**Encoding**: standard base64. It is recommended to send it **without line breaks**; if the image is provided as "wrapped" base64 (CRLF line breaks), the service normalizes them automatically. The `template` returned in the response is **single-line base64**.

#### Capture types (scanType)

| Value    | Description                                             | Support (current version)                 |
| -------- | ------------------------------------------------------- | ----------------------------------------- |
| `Plain`  | Plain / live capture (finger placed flat)               | **Supported** (default value)             |
| `Rolled` | Rolled capture (the finger is rolled from side to side) | Requires an image captured in rolled mode |
| `Latent` | Latent / forensic fingerprint                           | Requires a latent image                   |

* If omitted, `Plain`.
* The `scanType` must correspond to the type of image sent. For standard onboarding capture (including widget capture), use **`Plain`**.
* If the engine cannot generate the template using the specified mode (for example, a plain image sent as `Rolled`/`Latent`), the service responds **`400`** with the engine's message (e.g., `"Finger template creation failed"`), not a `502`.

#### Example Request

```json
{
  "fingers": [
    {
      "position": 2,
      "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo...",
      "dpi": 500,
      "scanType": "Plain"
    }
  ]
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** Base64 or tokenized fingerprint images (`fingers[].tokenBuffer`, 1 to 10 per request) count toward this limit together, 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.                                                 |
| `serviceResultLog`     | string  | Descriptive result field or error message, if applicable.                                                        |
| `serviceTime`          | string  | Total processing time **(milliseconds)**.                                                                        |
| `serviceTransactionId` | string  | Transaction identifier associated with the request processed by the API.                                         |
| `templates`            | array   | List of extracted templates, one for each fingerprint submitted. See [Template fields](#campos-de-la-plantilla). |

#### Template fields

| Field            | Type    | Description                                                                             |
| ---------------- | ------- | --------------------------------------------------------------------------------------- |
| `position`       | integer | Finger position (1–10) corresponding to the template.                                   |
| `template`       | string  | Extracted Biometric Template, encoded in Base64. Reusable in `authenticateFingerprint`. |
| `overallQuality` | integer | Overall fingerprint quality.                                                            |
| `nfiq2`          | number  | Quality score **NFIQ 2.0**.                                                             |
| `nfiq`           | number  | Quality score **NFIQ**.                                                                 |
| `quality`        | number  | Biometric engine quality score.                                                         |
| `dpi`            | integer | Resolution used to process the fingerprint.                                             |
| `scanType`       | string  | Processed capture type (`Plain`, `Rolled`, `Latent`).                                   |

#### 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       |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Service request successfully processed",
  "serviceTime": "742",
  "serviceTransactionId": "b2f6297b-01ca-4aa3-afd7-6cb3c9d74141",
  "templates": [
    {
      "position": 2,
      "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA...",
      "overallQuality": 82,
      "nfiq2": 78.0,
      "nfiq": 2.0,
      "quality": 0.91,
      "dpi": 500,
      "scanType": "Plain"
    }
  ]
}
```

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