Use Case: Patient Identity in Health Records

A health-record solution must answer one question before it does anything else: is this the person whose record I am about to open? Get it wrong and a clinician reads someone else's history, or writes a diagnosis into the wrong file. Get it wrong in the other direction - demand a fingerprint from a patient whose hands are damaged, at a clinic with no working reader - and the patient is turned away.

This is a reference workflow for that decision, applying the NIMC Identity API to the health-records template.

Assurance decision

Reading and writing clinical data is irreversible in effect - a wrong entry propagates into later care - so it sits at high assurance. Registration sits a step lower: a duplicate record is a data-quality problem, correctable, not a clinical one.

Offer both biometric modalities where the clinic can support them. A patient whose fingerprints will not capture - manual workers, older patients, patients with certain skin conditions or hand injuries - is not an edge case in a Nigerian clinic, and neither is a clinic whose fingerprint reader has failed. Facial authentication with liveness, available through NINAuth and NIMC verification partners, needs only a camera and reaches those patients. A service with one biometric route has a single point of exclusion.

Workflow: first registration

1. Explain and record consent. The patient is told the clinic will verify their identity against the national register, for the purpose of creating a health record. Consent is recorded with a timestamp, the purpose, and the staff member who obtained it.
2. Collect the NIN from the patient and validate its format locally.
3. Call searchByNIN with the cached token.
4. On match, extract only the fields the record needs (see below) and create the patient record with an internal record ID as its key. The NIN is stored once, encrypted, as a verification reference - never as the primary key, and never displayed in the clinical UI.
5. Enrol a biometric reference for subsequent visits - a fingerprint confirmed against the NIN with verifyFingerWithData, or a facial authentication through NINAuth or a verification partner - so that the patient's later visits need no NIN re-entry. Where both are available, enrol both: the second modality is the fallback when the first fails.
6. Record the audit event: purpose, outcome, staff member, timestamp, correlation ID. Identifiers hashed.

Workflow: returning patient at the point of care

1. Confirm consent for this visit's lookup - consent is per lookup and purpose, not captured once at registration and reused indefinitely.
2. Capture the enrolled biometric - the fingerprint at its enrolled position, or a facial capture with liveness.
3. Call the matching 1:1 check - verifyFingerWithData with the NIN held against the record, the base64 fingerprint, and the position code; or the facial verification the organisation is onboarded for.
4. On a confirmed match, open the record and let care proceed.
5. Discard the biometric from memory immediately - face captures as strictly as fingerprints. Neither is written to disk, queued, or logged.
6. Record the audit event.

Either way the biometric is compared against the identity the record already claims - a 1:1 check. The solution never searches the national register for whoever matches the print or face in front of it.

Fields a health record may retain

The response arrives as a full demoData record. Minimisation happens at the integration boundary - the fields above are extracted, the rest is discarded before anything reaches clinical storage.

Failure paths

No match on NIN

Causes: mistyped NIN, a name recorded differently at registration, genuine non-enrolment. A patient is never refused care because the register did not match.

The flow: re-enter the NIN once; if it still does not match, create the record as unverified, flagged for later verification, and proceed with care. An unverified record is usable clinically and visibly marked as unverified, so that it is not later mistaken for a confirmed identity.

Biometric does not match

Causes, fingerprint: worn or damaged prints (common among manual workers, the elderly, and patients with certain conditions), a poor reader, a wet or dirty finger. Causes, facial: poor lighting, a low-quality camera, a face that has changed since registration, or a liveness check defeated by the environment rather than by the patient.

The flow: retry once; try an alternative finger if another position was enrolled; then switch modality - a patient whose prints will not read may verify by face, and the reverse. Only after both available routes fail does the flow fall back to staff-attested identification, where a named clinician confirms the patient by other means and the record notes who attested and why. Repeated biometric failure is a service-design signal, not a fraud signal.

eNVS unreachable

VPN down, upstream outage, clinic offline. Verification fails closed - the solution never assumes a pass - but care does not stop.

The degraded mode, agreed in advance with the health authority: the clinician proceeds using the record they can identify by other means, entries are written to a queue marked pending verification, and the queue is reconciled when the service returns. Whether this is acceptable, and for which actions, is a clinical governance decision recorded before launch.

What the AI layer sees

Where the solution has an AI assistant - summarising history, suggesting follow-up questions, drafting patient instructions - it operates on the clinical record, never on the identity record:

The agent cannot call eNVS. Verification happens in the solution's integration layer and reaches the agent only as a flag, through a bounded tool following the DiCert MCP pattern.

Pre-launch checklist

1. Assurance levels agreed per action with the health authority, in writing.
2. Consent wording and storage reviewed for clinical context and NDPA compliance.
3. Field retention list signed off; the discard step tested against a full demoData response.
4. No-match path tested end to end, including the unverified-record route.
5. Biometric failure path tested for each modality offered, including the switch between them and the staff-attested fallback.
6. Degraded mode agreed with clinical governance and the reconciliation queue tested.
7. NIN confirmed absent from logs, URLs, analytics, and the clinical UI.
8. Agent tool surface reviewed: no identity fields reachable by the model.