Authenticate Fingerprint

Service that performs the 1:1 Fingerprint Biometric Verification, comparing a fingerprint from probe against a fingerprint from gallery of the same position. Each side can be provided as open/tokenized image or as Biometric Template previously extracted with Fingerprint Extraction, allowing a combination of both formats.

Endpoint

POST /services/authenticateFingerprint

Headers

Name	Type	Required	Description
x-api-key	string	Yes	API Key for access authorization.
family	string	No	Value: Onboarding. Required with the tracking service.

All calls to the tracking Endpoints with Identity Platform must contain the header family.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
probe	array	Yes	Reference Fingerprint. Must contain exactly one element.
gallery	array	Yes	Comparison Fingerprint. Must contain exactly one element, of the same position as the probe.
probe[].position / gallery[].position	integer	Yes	Finger position according to the NIST numbering (1–10). Must match between probe and gallery.
probe[].tokenBuffer / gallery[].tokenBuffer	string	Conditional	Fingerprint image in Base64 or a token from FacePhi. Required if not sent template. See Accepted formats.
probe[].template / gallery[].template	string	Conditional	Biometric Template (Base64) obtained from extractFingerprint. Required if not sent tokenBuffer. See Accepted formats.
threshold	integer	No	Decision threshold. If omitted, the tenant value or the biometric engine value is used.
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains Tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

The comparison method is automatically derived from the format of probe and gallery (image or template). See Method specification.

Accepted formats

• Image (tokenBuffer): Base64 of a fingerprint image in WSQ, BMP, PNG, JPEG or JP2, or a token from FacePhi.

• Template (template): the template in Base64 returned by extractFingerprint (fingerprint already converted to a Biometric Template).

• Encoding: standard base64, preferably without line breaks. If it arrives "wrapped" (CRLF breaks), the service normalizes it before processing.

Method specification

Method	Description	Input
1	Authentication using two images	probe: image, gallery: image
2	Authentication using two Biometric Templates	probe: template, gallery: template
3	Authentication using a image and a template	probe: image, gallery: template
4	Authentication using a template and a image	probe: template, gallery: image

Request example

{
  "probe": [
    {
      "position": 2,
      "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo..."
    }
  ],
  "gallery": [
    {
      "position": 2,
      "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA..."
    }
  ],
  "threshold": 40,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code that indicates the overall result of the service execution. See Service Result Code.
serviceResultLog	string	Descriptive field for the result of the service execution.
serviceTime	string	Total processing time (milliseconds).
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
serviceFingerprintAuthStatus	string	Match result. See Fingerprint Auth Status.
serviceFingerprintScore	number	Similarity score between the two Fingerprint samples compared.
serviceFingerprintThreshold	number	Decision threshold applied in the comparison.

Service Result Code

serviceResultCode	Description	HTTP code
0	The service execution was successful, the module processed the request correctly.	200
-1	The biometric engine could not complete the comparison (unprocessable input).	200

Fingerprint Auth Status

Status	Description
MATCH	The comparison is positive: the Fingerprint samples match.
NO_MATCH	The process ran successfully but the Fingerprint samples do not match.
ERROR	The comparison could not be performed (for example, invalid input or input unprocessable by the engine).

Response example: MATCH

{
  "serviceResultCode": 0,
  "serviceResultLog": "match",
  "serviceTime": "318",
  "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "serviceFingerprintAuthStatus": "MATCH",
  "serviceFingerprintScore": 62.00000000,
  "serviceFingerprintThreshold": 40.00000000
}

Response example: NO_MATCH

{
  "serviceResultCode": 0,
  "serviceResultLog": "no_match",
  "serviceTime": "305",
  "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "serviceFingerprintAuthStatus": "NO_MATCH",
  "serviceFingerprintScore": 12.00000000,
  "serviceFingerprintThreshold": 40.00000000
}

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