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.

post

Autorizações

AuthorizationstringObrigatório

HS256 JWT signed with auth_jwt_secret and carrying an exp claim, sent as Authorization: Bearer <jwt>. Accepted while auth_accept_authorization_header is true (default). Only enforced when auth_enabled is true.

Corpo

imagestringObrigatório

Fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2.

Example: <base64_image>

positionstring · enumObrigatório

Public finger position name.

Example: RightIndexValores possíveis:

Respostas

200

Public extract response.

application/json

Public extract response.

fingerTemplatestringObrigatório

Generated fingerprint template, encoded in Base64. Use it as fingerTemplate1 or fingerTemplate2 in POST /api/v1/finger/authenticate.

Example: <base64_template>

positionstring · enumObrigatório

Public finger position name.

Example: RightIndexValores possíveis:

scanTypestring · enumObrigatório

Capture type of the fingerprint image.

Example: PlainValores possíveis:

qualityintegerOpcional

Overall quality score (0-100, higher is better). Present when the processing components report it and options.includeQuality is not false.

Example: 88

sdkDurationinteger · int64Obrigatório

Processing time in milliseconds.

Example: 123

queueDurationinteger · int64Obrigatório

Time the request waited in the queue, in milliseconds.

Example: 2

400

The request is invalid or could not be processed. message carries the reason; see the operation description for the values it can take.

application/json

401

JWT authentication is enabled and the request carries no token or an invalid one. message is one of Missing authentication token, JWT token is expired, JWT token does not include exp claim, JWT token validation failed or, when auth_jwt_secret is empty, Authentication secret is not configured.

application/json

404

The route is not registered on this node. The fingerprint operations only exist on nodes started with the master role. This response is produced by the HTTP server and does not carry the standard error body.

413

The request body exceeds client_max_body_size. This response is produced by the HTTP server before the request reaches the service and does not carry the standard error body.

500

Unhandled internal error. exception carries the detail.

application/json

post/api/v1/finger/extract

POST /api/v1/finger/extract HTTP/1.1
Host: 127.0.0.1:6982/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 113

{
  "image": "<base64_image>",
  "position": "RightIndex",
  "options": {
    "dpi": 500,
    "scanType": "Plain",
    "includeQuality": true
  }
}

{
  "fingerTemplate": "<base64_template>",
  "position": "RightIndex",
  "scanType": "Plain",
  "quality": 88,
  "qualityDetails": {
    "nfiq2": 79,
    "nfiq": 1,
    "score": 88
  },
  "sdkDuration": 123,
  "queueDuration": 2
}