Schemas

ID number of the biometrics agent signed into the workstation's hardware server application. Recorded against the match attempt for audit. Example is dummy data.

Targets 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.

Required. 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.

Required. Identifier of the workstation that performs the capture, obtained from the hardware server application running on the authorizing device.

Advanced. 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.

Optional. 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.

Path to read for the state of the match. Provided as a reconciliation read for a caller that missed its callback, not as an instruction to poll.

Minimum milliseconds between reconciliation reads of endpoint. It bounds how often that read is worth repeating; it is not a polling interval for the primary result.

What the client should do next. await_callback - the capture is running and the verdict will be pushed to the facility's registered callback endpoint; there is nothing to poll. poll - the capture is running but this facility has no registered endpoint, so read endpoint until the status is terminal. none - the match has resolved.

Identifier 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.

Machine-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.

Human-readable detail accompanying error_code. Safe to log or surface to an operator; do not branch on it.

RFC 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.

Identifier 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.

true 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.

Lifecycle 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.

Required. ID number of the biometrics agent signed into the workstation's hardware server application. Recorded against the capture for audit. Example is dummy data.

Required. The minor's beneficiary Client Registry code, including the dependant suffix. Dependants are distinguished only by the trailing index, so send exactly the code of the child whose finger is on the scanner. Example is dummy data.

Required. Serial number of the capture device on the workstation, read from the local agent's device list.

Required. The finger position being enrolled, from 1 to 10. Enrollment is per finger, so a beneficiary is enrolled one position at a time.

Required. Identifier of the workstation that performs the capture, obtained from the hardware server application running on the authorizing device.

Advanced. 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.

Reference for this capture request. The completion callback carries the same value, so use it to tie the callback back to the request that produced it.

Always await_callback. The verdict is pushed to the facility's registered callback endpoint when the capture resolves; there is nothing to poll.

Acknowledgement state of the dispatched capture. dispatched means it reached the workstation and the finger has not been read yet. The result is not here; it arrives on the callback.

Required. ID number of the biometrics agent signed into the workstation's hardware server application. Recorded against the capture for audit. Example is dummy data.

Required. The minor's beneficiary Client Registry code, including the dependant suffix. Send exactly the code of the child whose finger is on the scanner. Example is dummy data.

Required. Serial number of the capture device on the workstation, read from the local agent's device list.

Required. The finger position being verified, from 1 to 10. It must be a position that was already enrolled; verifying confirms that enrolled print.

Required. Identifier of the workstation that performs the capture, obtained from the hardware server application running on the authorizing device.

Advanced. 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.

Overall enrollment state: fully_enrolled when every expected finger is stored and verified, partially_enrolled when some are still outstanding, and an empty string when the beneficiary has no stored prints.

Finger positions that are stored but still awaiting confirmation. Resume the enrollment on these positions; they cannot satisfy a match request yet.

Total number of finger positions stored for the beneficiary, verified and non-verified combined.

Finger positions that are stored and confirmed. Any of these can satisfy a match request; pass one of them as position to target a specific finger.

The patient's Client Registry identifier. Dummy example — obtain a real value from the Patient Search API.

Type of service being authorized.

One-time password delivered to the patient's registered phone number.

List of intervention codes for the services being requested in this visit.

ID number of the registered biometrics agent. Obtained from the user logged into the hardware server application. Example is dummy data.

Operating system of the device making the biometrics request.

Name of the healthcare facility initiating the eKYC verification.

Biometric verification flow(s) to use. SHA triggers the eKYC flow; fingerprint is used for Under-18 patient consent. The fingerprint option (Under-18 patient flow) is still work in progress.

List of intervention codes for the services being requested in this visit.

Set to true only when this authorization is for a patient's discharge. false for all other consent scenarios.

Set to true if this authorization is for an emergency claim.

Indicates an integration with external systems. Always true for system-to-system integrations.

The patient's Client Registry identifier. Dummy example — obtain a real value from the Patient Search API.

The healthcare facility's Facility Registry (FR) code.

Type of service being authorized.

Workstation identifier obtained from the hardware server application running in the background on the authorizing device.

List of intervention codes for the services being requested in this visit.

Set to true only when this authorization is for a patient's discharge. false for all other consent scenarios.

Set to true if this authorization is for an emergency claim.

Indicates an integration with external systems. Always true for system-to-system integrations.

Identifier of the completed fingerprint match, returned by POST /api/v1/biometrics/matches and read back from GET /api/v1/biometrics/matches/{match_id}. It is the gateway's own record of a completed fingerprint match, so no biometric credential is sent here. The match must have reached the matched state, must still be inside its 600 second freshness window, and is single-use: once an authorization has been minted from it, reuse is refused. The patient_id sent here must equal the health_id the match was captured against.

The minor's Client Registry identifier, including the dependant suffix. It must be the same value sent as health_id when the match was requested; the gateway compares the two and refuses a mismatch. Example is dummy data.

The healthcare facility's Facility Registry (FR) code.

Type of service being authorized.

@Description HTTP status text from the standard HTTP status codes @Example "Bad Request"

@Description Detailed error message explaining what went wrong @Example "token missing required tenant_id claim"

List of SHA intervention codes for the services being authorized in this visit.

The beneficiary's Client Registry identifier (dummy example).

Identifier of the specific registered contact to which the OTP should be sent. When omitted, the beneficiary's primary confirmed contact is used. This ID can be obtained from the Get Beneficiary Contacts endpoint.

@Description Response data payload containing operation details @Example {"status": "success"}

@Description Success message describing the operation result @Example "Visit has been successfully started"

Consent token issued when the visit was authorized, required to authorize the discharge OTP (dummy example).

The beneficiary's Client Registry identifier (dummy example).

Delay before the first retry, in milliseconds.

Factor the delay is multiplied by after each failed attempt.

Number of retries after the initial attempt.

The event this operation answers. status_changed for status callbacks.

When the operation was registered.

The parent endpoint this operation belongs to.

Static headers sent on this operation's deliveries, on top of the endpoint's own.

Internal row identifier. Address the operation by operation_id, not by this.

Whether this operation is eligible for delivery. Both the endpoint and the operation must be active.

HTTP method the HIE uses when calling your endpoint. DELETE is accepted at registration but is not supported at delivery time, so use POST for status callbacks.

Your label for the operation.

The identifier to use on the read, update and delete routes.

Path appended to the endpoint's base_url unless path_url_override is set.

Absolute URL that replaces base_url + path when set. Returned as null when unused.

Content type of the delivered body.

Retry policy applied when a delivery attempt does not return a 2xx.

Response deadline for this operation. null means the endpoint's value applies.

When the operation was last changed.

How the HIE authenticates when it calls your endpoint. none is the only value you can set yourself: every other value needs a secret_ref, and secrets are provisioned by the HIE rather than through the API.

Scheme and host each operation's path is appended to.

When the endpoint was registered.

The identifier to use when registering operations, and on the update and delete routes.

Which entity's status changes reach this endpoint: claim, preauth or authorization.

Which of your environments this endpoint belongs to. Only production and sandbox are accepted; prod is rejected.

Facility Registry code this endpoint serves. The fallback selector at delivery time.

Static headers sent on every delivery to this endpoint.

Internal row identifier. Address the endpoint by endpoint_id, not by this.

Whether this endpoint is eligible for delivery. Nothing is delivered while it is false, and no error is raised.

Your label for the endpoint.

The operations registered under this endpoint. Empty until you register one - an endpoint on its own delivers nothing.

Reference to the credential the HIE uses. Empty when auth_type is none. The credential itself is never returned.

Primary selector, matched against the tenant_code the EDI backend publishes before facility_fr_code is tried. Normally the same value as your client ID, and unique to you.

The tenant that owns this endpoint, as resolved from the path when it was registered.

How long the HIE waits for your response before treating the attempt as failed.

When the endpoint was last changed.

Delay before the first retry, in milliseconds.

Factor the delay is multiplied by after each failed attempt. With backoff_ms: 1000 and a multiplier of 2, retries are spaced 1s, 2s, 4s.

Number of retries after the initial attempt.

How the HIE authenticates to your endpoint. Required. none is the only value you can set yourself; every other value also requires secret_ref, and secrets are stored by the HIE out of band.

Scheme and host the operation path is appended to. Required, and must be an absolute URL.

Which entity's status changes this endpoint receives. Required, and must be one of the three values listed. A facility holds at most one endpoint per entity type, so register a separate endpoint for each kind you want.

Required. production or sandbox. prod is rejected.

Your label for the endpoint. Required. It is not parsed and does not have to be unique.

Facility Registry code this endpoint serves. Used as the fallback selector at delivery time when no tenant matches tenant_code, and as a lookup key on GET /tenants/{tenant_id}/endpoints.

Static headers sent on every delivery to this endpoint. Use them for routing or tracing values, never for credentials.

Retry policy for deliveries to this endpoint. Omit it to accept the platform default.

Reference to the credential the HIE uses for this endpoint. Required whenever auth_type is not none. The HIE issues the value; there is no API route that stores a secret.

Selector matched first at delivery time against the tenant_code the EDI backend publishes. This is normally the same value as your client ID, and it is unique to you. Defaults to the resolved tenant's own code when omitted, which is usually what you want.

How long the HIE waits for your response before treating the attempt as failed. Defaults to 60000.

The event this operation answers. Required. For status callbacks it is always status_changed, whatever the entity type.

HTTP method the HIE calls with. Required, one of GET, POST, PUT, PATCH, DELETE. Use POST: DELETE passes validation here but fails at delivery time.

Your label for the operation. Required.

Static headers for this operation, in addition to the endpoint's own.

Path appended to the endpoint's base_url. Required unless you send path_url_override.

Absolute URL that replaces base_url + path entirely. Use it when this one callback must go somewhere other than the endpoint's host; the endpoint's base_url is then ignored for this operation.

Content type of the delivered body. Defaults to application/json, which is what the status-callback payload is.

Retry policy for deliveries to this endpoint. Omit it to accept the platform default.

Response deadline for this operation, overriding the endpoint's value.

New authentication mechanism. Changing it to anything other than none needs a secret_ref the HIE has issued.

New scheme and host. Must be an absolute URL.

Move this endpoint to a different entity type. Must be one of the three values listed. Changing it re-points a live integration, so it is rarely what you want on a working registration.

production or sandbox.

Replaces the stored header map wholesale rather than merging into it.

Set to false to stop delivery without deleting the registration. Nothing is delivered while this is false, and no error is raised - the first thing to check when callbacks stop arriving.

New label for the endpoint.

New credential reference, issued by the HIE.

New primary selector, matched against the tenant_code the EDI backend publishes.

New response deadline in milliseconds.

New action. Changing it away from status_changed stops status callbacks reaching this operation.

Replaces the stored header map wholesale rather than merging into it.

Set to false to stop delivery without deleting the operation. Both the endpoint and the operation must be active for anything to arrive, and an inactive record raises no error.

New HTTP method, one of GET, POST, PUT, PATCH, DELETE.

New label for the operation.

New path, appended to the endpoint's base_url.

New absolute URL, replacing base_url + path for this operation.

New content type for the delivered body.

New response deadline for this operation, in milliseconds.