Endpoints for capturing a fingerprint match for a minor and attesting consent on their behalf from that match.
Request a fingerprint match for a minor
Dispatches a fingerprint match for a minor to a registered workstation and records the attempt. The call is asynchronous: it returns 202 with a match_id, not a match verdict.
The verdict is delivered to the facility's registered callback endpoint when the capture resolves - the same endpoint that already receives claim notifications, so it inherits its authentication, signing and retries. next_action is await_callback; there is nothing to poll. On a successful match the callback carries the match_id to present to POST /api/v1/claims/visit or POST /api/v1/claims/authorize; on an unsuccessful one it carries the reason.
health_id, workstation_id, device_id and agent_id are all required. A request missing any of them is rejected with 400 naming the field, rather than being dispatched and failing at the workstation with an opaque device error. Send the child's own beneficiary Client Registry code, including the dependant suffix, in health_id - it must equal the patient_id supplied later, or the authorization is refused as a subject mismatch.
Related documentation: Minors Biometrics Consent
Request a fingerprint match for a minor › Request Body
agent_idID number of the biometrics agent signed into the workstation's hardware server application. Recorded against the match attempt for audit. Example is dummy data.
device_idTargets a specific capture device on the workstation, read from the local agent's device list. A workstation with a single reader does not need it.
health_idRequired. The minor's beneficiary Client Registry code, including the dependant suffix, and the same value the workstation agent enrolled the child against. Dependants are distinguished only by the trailing index, so a principal's code and a dependant's differ by one character - send exactly the code of the child whose finger is on the scanner. This value must equal the patient_id sent later to POST /api/v1/claims/visit or POST /api/v1/claims/authorize; authorization compares the two and refuses a mismatch. Example is dummy data.
workstation_idRequired. Identifier of the workstation that performs the capture, obtained from the hardware server application running on the authorizing device.
deadline_secondsAdvanced. Seconds the capture window stays open before the attempt is abandoned. Leave it unset unless you have a reason to widen or narrow the window; the platform default suits a normal point-of-care capture.
positionOptional. Finger position to match against. Defaults to 0, which for a minor means any enrolled finger. Use the positions reported by GET /api/v1/biometrics/enrollment-status to target a specific finger.
Request a fingerprint match for a minor › Responses
Accepted - match dispatched to the workstation. The verdict arrives at the registered callback endpoint
authorization_idIdentifier of the authorization minted from this match. A match is single-use: once this is set, any further attempt to authorize with the same match_id is refused. Absent until the match has been used.
error_codeMachine-readable code explaining a match that did not succeed. Branch on this rather than on error_detail. deadline_exceeded means the capture window closed with no result from the workstation, which is an abandoned attempt rather than a verdict on the finger. Absent while the match is pending and on a successful match.
error_detailHuman-readable detail accompanying error_code. Safe to log or surface to an operator; do not branch on it.
expires_atRFC 3339 timestamp after which the match can no longer authorize. Anchored on the capture instant reported by the workstation plus a 600 second freshness window, so a late read cannot extend it. Absent until the capture reaches a terminal state.
match_idIdentifier of the match record created by POST /api/v1/biometrics/matches. Read it back from GET /api/v1/biometrics/matches/{match_id} while the status is pending, then present it as match_id when starting a visit or creating an authorization.
matchedtrue only when the capture resolved to a successful match. false for every other status, including pending.
The caller's next step. While the match is running the type is await_callback and the verdict is pushed to the registered callback endpoint; once the match is terminal the type is none.
statusLifecycle state of a match attempt. pending means the capture has not resolved and no callback has been sent. matched is the only state that can authorize. no_match means the capture ran and the finger did not match the enrolled prints. failed means the attempt produced no verdict, for example when the capture window closed - see error_code. no_match and failed are terminal and require a fresh capture.
Read a minor's fingerprint match
Returns the current state of a match, finalizing it first if the underlying capture has resolved.
This is a reconciliation read for a caller that missed its callback, not the primary delivery path: The verdict is delivered to the facility's registered callback endpoint when the capture resolves - the same endpoint that already receives claim notifications, so it inherits its authentication, signing and retries. next_action is await_callback; there is nothing to poll. It should not be called in a loop.
status is one of pending, matched, no_match or failed. matched is the only state that can authorize; no_match and failed are terminal and need a fresh capture. When a match does not succeed, error_code carries a machine-readable code, including deadline_exceeded when the capture window closed with no result.
Related documentation: Minors Biometrics Consent
path Parameters
match_idIdentifier of the match, returned by POST /api/v1/biometrics/matches. Example is dummy data.
Read a minor's fingerprint match › Responses
OK - Current state of the match
authorization_idIdentifier of the authorization minted from this match. A match is single-use: once this is set, any further attempt to authorize with the same match_id is refused. Absent until the match has been used.
error_codeMachine-readable code explaining a match that did not succeed. Branch on this rather than on error_detail. deadline_exceeded means the capture window closed with no result from the workstation, which is an abandoned attempt rather than a verdict on the finger. Absent while the match is pending and on a successful match.
error_detailHuman-readable detail accompanying error_code. Safe to log or surface to an operator; do not branch on it.
expires_atRFC 3339 timestamp after which the match can no longer authorize. Anchored on the capture instant reported by the workstation plus a 600 second freshness window, so a late read cannot extend it. Absent until the capture reaches a terminal state.
match_idIdentifier of the match record created by POST /api/v1/biometrics/matches. Read it back from GET /api/v1/biometrics/matches/{match_id} while the status is pending, then present it as match_id when starting a visit or creating an authorization.
matchedtrue only when the capture resolved to a successful match. false for every other status, including pending.
The caller's next step. While the match is running the type is await_callback and the verdict is pushed to the registered callback endpoint; once the match is terminal the type is none.
statusLifecycle state of a match attempt. pending means the capture has not resolved and no callback has been sent. matched is the only state that can authorize. no_match means the capture ran and the finger did not match the enrolled prints. failed means the attempt produced no verdict, for example when the capture window closed - see error_code. no_match and failed are terminal and require a fresh capture.