> 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 fingerprint images, open or tokenized. Each image becomes a template (`template`) reusable in the fingerprint authentication service.

{% hint style="warning" %}
Please note that the returned quality values are estimates based on the provided fingerprint image. The 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**  | Access authorization API Key.                              |
| **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. Supports **1 to 10** fingerprints per request (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 default value (500) is used.                                |
| `fingers[].scanType`    | string  | No       | Capture type (`Plain` 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 field `tokenBuffer` supports a fingerprint image encoded in **Base64**, or a **token** from FacePhi (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 comes with 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`  | Flat/live capture (finger laid 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 the Widget) use **`Plain`**.
* If the engine cannot generate the template with the indicated mode (for example, a flat image sent as `Rolled`/`Latent`), the service responds **`400`** with the engine message (e.g. `"Finger template creation failed"`), not a `502`.

#### Request example

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

### Responses

#### `200` Success

#### Response parameters

| Parameter              | Type    | Description                                                                                                 |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`    | integer | Code that indicates the **overall result** from service execution.                                          |
| `serviceResultLog`     | string  | Descriptive field of the result 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 sent. 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"
}
```

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