Fingerprint Extraction

Service that performs the capture and extraction of Biometric Templates for Fingerprint from Fingerprint images, open or tokenized. Each image is converted into a template (template) reusable in the Fingerprint authentication service.

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.

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. Supported from 1 to 10 Fingerprints per request (configurable per tenant).
fingers[].position	integer	Yes	Finger position according to the NIST numbering (1–10). See Finger positions.
fingers[].tokenBuffer	string	Yes	Fingerprint image in Base64 or a token FacePhi token. See Accepted formats.
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.

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 FacePhi token (tokenized reference that the service resolves internally).

Image formats supported by the engine:

Format	Description
WSQ	Wavelet Scalar Quantization (fingerprint standard; common format of 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 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 Fingerprint / forensic	Requires a latent image

• If omitted, use 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

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

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code indicating the overall result of the 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.

Template fields

Field	Type	Description
position	integer	Finger position (1–10) corresponding to the template.
template	string	Extracted Biometric Template, Base64-encoded. 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

{
  "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

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "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

{
  "message": "Endpoint request timed out"
}