> 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-pt-br/sdks/backend-sdk/finger/technical_documentation/api_reference/finger-operations/extract-a-fingerprint-template.md).

# Extract a fingerprint template

**IMPORTANT - BREAKING CHANGE (2.0.0).** This endpoint is not compatible with 1.x.x. It uses the public contract (`image`, `position`, `options`) and returns public fields (`fingerTemplate`, `quality`, `qualityDetails`, `sdkDuration`, `queueDuration`).

Generates a fingerprint template from a fingerprint image. Supported input formats for `image`: wsq, bmp, png, jpg, jp2. Only available on `master` nodes.

Validation errors (HTTP `400`), checked in this order before the image is processed:

| Case                                                     | `message`                                                      |
| -------------------------------------------------------- | -------------------------------------------------------------- |
| The body is not a JSON object sent as `application/json` | `Value, object or array expected.`                             |
| `image` is missing                                       | `Key image not found`                                          |
| `image` is not a string, or is empty                     | `Key image is not a string`, `Key image is empty string`       |
| `position` is missing                                    | `Key position not found`                                       |
| `position` is not a string, or is empty                  | `Key position is not a string`, `Key position is empty string` |
| `options` is not an object                               | `Key options is not an object`                                 |
| `options.dpi` is not an unsigned integer                 | `Key dpi is not an unsigned integer`                           |
| `options.scanType` is not a string, or is empty          | `Key scanType is not a string`, `Key scanType is empty string` |
| `options.includeQuality` is not a boolean                | `Key includeQuality is not a bool`                             |
| `image` is not valid Base64                              | `Malformed Base64 input`                                       |
| `position` is not one of the documented values           | `Invalid finger position`                                      |
| `options.dpi` is outside 250-1000                        | `Invalid dpi value`                                            |
| `options.scanType` is not one of the documented values   | `Invalid scanType value`                                       |

Processing errors (HTTP `400`):

| `message`                                              | Cause                                                                                                                                                                                                     |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Finger template creation failed`                      | The processing components could not generate a template from the image                                                                                                                                    |
| `Invalid response from Engine`                         | The processing components returned a response the service cannot interpret                                                                                                                                |
| `Fingerprint processing communication error: <detail>` | The processing components could not be reached or answered with an HTTP error. `<detail>` is, for example, `Too many retries` when they kept failing after the retries configured in `engine_max_retries` |
| `Service not initialized`, `Service not configured`    | The service is not ready yet                                                                                                                                                                              |

Only successful extractions increase the usage counters and feed the quality figures of `GET /api/v1/finger/metrics`.

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"tags":[{"name":"Finger Operations","description":"Fingerprint template extraction and 1:1 authentication. These endpoints use the public payload contract\nintroduced in 2.0.0 and are only registered on `master` nodes.\n"}],"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"HS256 JWT signed with `auth_jwt_secret` and carrying an `exp` claim, sent as `Authorization: Bearer <jwt>`.\nAccepted while `auth_accept_authorization_header` is `true` (default). Only enforced when `auth_enabled` is\n`true`.\n"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same JWT, sent as is (without the `Bearer` prefix) in the header named by `auth_api_key_header_name`\n(`x-api-key` by default). Accepted while `auth_accept_api_key_header` is `true` (default). Only enforced when\n`auth_enabled` is `true`.\n"}},"schemas":{"ExtractRequest":{"type":"object","required":["image","position"],"properties":{"image":{"type":"string","description":"Fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2."},"position":{"$ref":"#/components/schemas/FingerPosition"},"options":{"$ref":"#/components/schemas/ExtractOptions"}}},"FingerPosition":{"type":"string","description":"Public finger position name.","enum":["RightThumb","RightIndex","RightMiddle","RightRing","RightLittle","LeftThumb","LeftIndex","LeftMiddle","LeftRing","LeftLittle"]},"ExtractOptions":{"type":"object","description":"Optional tuning parameters of the extraction.","properties":{"dpi":{"type":"integer","description":"Resolution of the fingerprint image in dots per inch.","minimum":250,"maximum":1000,"default":500},"scanType":{"$ref":"#/components/schemas/ScanType"},"includeQuality":{"type":"boolean","description":"When `false`, the response omits `quality` and `qualityDetails`, and the extraction is not taken into\naccount in the quality figures of `GET /api/v1/finger/metrics`.\n","default":true}}},"ScanType":{"type":"string","description":"Capture type of the fingerprint image.","enum":["Plain","Rolled","Latent"]},"ExtractResponse":{"type":"object","description":"Public extract response.","required":["fingerTemplate","position","scanType","sdkDuration","queueDuration"],"properties":{"fingerTemplate":{"type":"string","description":"Generated fingerprint template, encoded in Base64. Use it as `fingerTemplate1` or `fingerTemplate2` in `POST /api/v1/finger/authenticate`."},"position":{"$ref":"#/components/schemas/FingerPosition"},"scanType":{"$ref":"#/components/schemas/ScanType"},"quality":{"type":"integer","description":"Overall quality score (0-100, higher is better). Present when the processing components report it and\n`options.includeQuality` is not `false`.\n"},"qualityDetails":{"$ref":"#/components/schemas/QualityDetails"},"sdkDuration":{"type":"integer","format":"int64","description":"Processing time in milliseconds."},"queueDuration":{"type":"integer","format":"int64","description":"Time the request waited in the queue, in milliseconds."}}},"QualityDetails":{"type":"object","description":"Detailed quality figures. Each field is only present when the processing components report it.","properties":{"nfiq2":{"type":"number","format":"float","description":"NFIQ 2 quality score, on a 0-100 scale where a higher value means a better capture."},"nfiq":{"type":"number","format":"float","description":"NFIQ quality level."},"score":{"type":"number","format":"float","description":"Quality score of the fingerprint."}}},"BadRequestResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."},"UnauthorizedResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"ExceptionResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"exception":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","exception","timeStamp"]}},"responses":{"BadRequest":{"description":"The request is invalid or could not be processed. `message` carries the reason; see the operation\ndescription for the values it can take.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}},"Unauthorized":{"description":"JWT authentication is enabled and the request carries no token or an invalid one. `message` is one of\n`Missing authentication token`, `JWT token is expired`, `JWT token does not include exp claim`,\n`JWT token validation failed` or, when `auth_jwt_secret` is empty, `Authentication secret is not configured`.\n","headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWW-Authenticate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResult"}}}},"NotFoundOnWorker":{"description":"The route is not registered on this node. The fingerprint operations only exist on nodes started with the\n`master` role. This response is produced by the HTTP server and does not carry the standard error body.\n"},"PayloadTooLarge":{"description":"The request body exceeds `client_max_body_size`. This response is produced by the HTTP server before the\nrequest reaches the service and does not carry the standard error body.\n"},"InternalError":{"description":"Unhandled internal error. `exception` carries the detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer` on `401` responses.","schema":{"type":"string"}}}},"paths":{"/api/v1/finger/extract":{"post":{"summary":"Extract a fingerprint template","description":"**IMPORTANT - BREAKING CHANGE (2.0.0).** This endpoint is not compatible with 1.x.x. It uses the public\ncontract (`image`, `position`, `options`) and returns public fields (`fingerTemplate`, `quality`,\n`qualityDetails`, `sdkDuration`, `queueDuration`).\n\nGenerates a fingerprint template from a fingerprint image. Supported input formats for `image`: wsq, bmp,\npng, jpg, jp2. Only available on `master` nodes.\n\nValidation errors (HTTP `400`), checked in this order before the image is processed:\n\n| Case | `message` |\n|---|---|\n| The body is not a JSON object sent as `application/json` | `Value, object or array expected.` |\n| `image` is missing | `Key image not found` |\n| `image` is not a string, or is empty | `Key image is not a string`, `Key image is empty string` |\n| `position` is missing | `Key position not found` |\n| `position` is not a string, or is empty | `Key position is not a string`, `Key position is empty string` |\n| `options` is not an object | `Key options is not an object` |\n| `options.dpi` is not an unsigned integer | `Key dpi is not an unsigned integer` |\n| `options.scanType` is not a string, or is empty | `Key scanType is not a string`, `Key scanType is empty string` |\n| `options.includeQuality` is not a boolean | `Key includeQuality is not a bool` |\n| `image` is not valid Base64 | `Malformed Base64 input` |\n| `position` is not one of the documented values | `Invalid finger position` |\n| `options.dpi` is outside 250-1000 | `Invalid dpi value` |\n| `options.scanType` is not one of the documented values | `Invalid scanType value` |\n\nProcessing errors (HTTP `400`):\n\n| `message` | Cause |\n|---|---|\n| `Finger template creation failed` | The processing components could not generate a template from the image |\n| `Invalid response from Engine` | The processing components returned a response the service cannot interpret |\n| `Fingerprint processing communication error: <detail>` | The processing components could not be reached or answered with an HTTP error. `<detail>` is, for example, `Too many retries` when they kept failing after the retries configured in `engine_max_retries` |\n| `Service not initialized`, `Service not configured` | The service is not ready yet |\n\nOnly successful extractions increase the usage counters and feed the quality figures of\n`GET /api/v1/finger/metrics`.\n","operationId":"extract","tags":["Finger Operations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractRequest"}}}},"responses":{"200":{"description":"Public extract response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFoundOnWorker"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```