Operations
The client.operations object (OpsManager) provides methods for fingerprint identification, person management, and image retrieval.
Overview
All operations automatically include the scanner's sensor serial number and device information when a DriverSocket is available. If no imageBase64 is provided, the SDK uses the last captured fingerprint result from the scanner.
Finger index
Finger indices follow the standard mapping:
Left hand
| Index | Finger |
|---|---|
| 0 | Thumb |
| 1 | Index |
| 2 | Middle |
| 3 | Ring |
| 4 | Little |
Right hand
| Index | Finger |
|---|---|
| 5 | Little |
| 6 | Ring |
| 7 | Middle |
| 8 | Index |
| 9 | Thumb |
Identify person
Identifies an existing person by their fingerprint. If the fingerprint matches a registered person, it returns their HHID. Otherwise, it returns an error with code 400.
const result = await client.operations.identifyPerson(
1, // idFinger — finger index
// score and imageBase64 are optional; uses last scanner result if omitted
);
console.log('Matched HHID:', result.hhid);
In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling
Validate fingerprint quality
There is an isScoreQualityEnough functionality with which to check if the fingerprint has the minimum quality necessary prior to sending it and not allow making the call to verify the fingerprint in such cases.
const isQualityEnough = await client.operations.isScoreQualityEnough(scoreUmbral);
This function returns true if the quality is higher than the limit passed as a parameter, and throws an error otherwise.
To do this, you must first make a call to getTenantScores to obtain the threshold value nfiq2ScoreMin. It is advisable to make this call after login and store the value for later use in isScoreQualityEnough.
const result = await client.operations.getTenantScores();
// result is the raw API response object:
// result.nfiq2ScoreMin - Minimum quality threshold that fingerprints must have
scoreUmbral = Number(result.nfiq2ScoreMin);
It is recommended to use the value received in nfiq2ScoreMin as the threshold in the registration process, and half of this as the threshold in the identification process.
Check fingerprint
Returns a temporary hash for the given fingerprint, used as input when registering a new person with createPerson. If the fingerprint is already registered, the response may also include the HHID.
const result = await client.operations.checkFingerprint(
1, // idFinger — finger index
// score and imageBase64 are optional; uses last scanner result if omitted
);
// result is the raw API response object:
// result.id — temporary hash (pass to createPerson)
console.log('Hash:', result.id);
If the fingerprint sent is already registered for the selected finger, an error code 409 and the HHID associated with that fingerprint are received within the error object: error.meta.cause.optionData.
In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling
Create person
Register a new person with their fingerprint data. Requires a hash list obtained from prior checkFingerprint calls and a consent flag.
// 1. Capture and check fingerprints to build hash list
const hash1 = await client.operations.checkFingerprint(1);
const hash2 = await client.operations.checkFingerprint(2);
// 2. Create person with collected hashes
const result = await client.operations.createPerson(
[hash1, hash2], // hashList
true, // consentTraining
);
console.log('Created person:', result[0].HHID);
If duplicates are detected among the submitted fingerprints, a 409 error code is returned, along with the finger groups (by their indexes) involved in those duplicates.
In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling
Delete fingerprint
Eliminate a fingerprint of a person. If the person only has that registered fingerprint or all the other registered fingerprints were previously deleted, the person will also be eliminated as a consequence of the deletion of their last fingerprint.
The first parameter corresponds to the person's HHID, and the second to the internal fingerprint identifier (more info).
await client.operations.deleteFingerprint(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 8
);
The HHID is validated as a UUID v4 before the request is sent. A ConfigError is thrown if the format is invalid.
In case of failure, or if the patient or the fingerprint does not exist or has been previously deleted, the system returns the corresponding error type. Consult the documentation related to the different types of errors and the examples of their handling, here: Error handling
Delete person
Delete a person and all their fingerprint data by HHID.
await client.operations.deletePerson(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
);
The HHID is validated as a UUID v4 before the request is sent. A ConfigError is thrown if the format is invalid.
In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling
Image retrieval
Access to fingerprint images requires specific permissions that must be granted by Heuristik. Contact the Heuristik team to request access.
| Method | Returns | Description |
|---|---|---|
getFingerprintImageAvailable(hhid) | number[] | List finger indices with stored images |
getFingerprintImage(hhid, idFinger) | string | Presigned URL — use as <img src> to display in the browser |
getFingerprintImageRaw(hhid, idFinger) | ArrayBuffer | Raw binary data — use to download as a file or process server-side |
getFingerprintImproveImage(hhid, idFinger) | string | Presigned URL for the enhanced image — use as <img src> to display |
getFingerprintImprove(hhid, idFinger) | ArrayBuffer | Raw binary data (enhanced) — use to download as a file |
// List available fingers
const fingers = await client.operations.getFingerprintImageAvailable(hhid);
// Returns an array of finger indices that have stored images
// e.g. [0, 5, 7] → Left Thumb, Right Little, Right Middle
// Get presigned URL (use directly as <img src="...">)
const url = await client.operations.getFingerprintImage(hhid, 1);
// Get raw BMP binary
const buffer = await client.operations.getFingerprintImageRaw(hhid, 1);
const blob = new Blob([buffer], { type: 'image/bmp' });
In case of failure, consult the documentation related to the different types of errors and the examples of their handling, here: Error handling
Method summary
| Method | Description |
|---|---|
identifyPerson(idFinger, score?, imageBase64?) | Identify person by fingerprint |
getTenantScores | Obtain quality thresholds |
isScoreQualityEnough | Validate if the quality of the fingerprint is above the minimum threshold |
checkFingerprint(idFinger, score?, imageBase64?) | Get temporary hash for registration |
createPerson(hashList, consentTraining) | Register new person |
deletePerson(hhid) | Delete person by HHID |
getFingerprintImageAvailable(hhid) | List available finger indices |
getFingerprintImage(hhid, idFinger) | Presigned URL for browser display |
getFingerprintImageRaw(hhid, idFinger) | Raw binary for download |
getFingerprintImproveImage(hhid, idFinger) | Enhanced image presigned URL for display |
getFingerprintImprove(hhid, idFinger) | Enhanced image raw binary for download |