Dependants and the hard cases
One adult with one card is the happy path, and no front desk needs help with it. The hard cases are the child with no document of their own, the patient who arrives unconscious, and the registry that will not answer.
Everything below elaborates this sentence.
Read 01 · Identify first. That page covers the step itself, meaning what a lookup is, the identifier pair, the four moves, the three identities and what breaks. This page only picks up what that one leaves out.
Identifying a dependant
This is the case that catches integrations out, because a dependant often has nothing to type into an ID field. There are two routes to them, and you need both.
The first route uses the dependant's own identifier. A child with a birth certificate or a birth notification is an ordinary lookup with nothing special about it, because the type field carries the difference.
The second route goes through the principal. The lookup response does not list a household.
Look the principal up, then read GET /api/v2/patients/{unique_patient_id}/metadata?consent_ref=…
with the facility headers, and let the operator choose from dependents[]. That call is gated on
a verified pii_access consent for the principal, taken at
03 · Consent, and without one it is refused with a 403
PII_CONSENT_REFUSED. The consent is verified, not spent, so the read can repeat. Everything in
it is unmasked.
Each dependent carries full_name, relationship, date_of_birth, gender and a registered
flag. A registered dependent has its own unique_patient_id, and only that one can have a visit
started for it. An unregistered one is on the household record but the patient index has no record
for it: it comes back with registered: false and no unique_patient_id rather than being
dropped. Some are legitimately pending. Render them separately, label them, and let the cover
check decide payability.
principal identifier + namedependents[] where relationship is a childdependents[] where relationship is a spousedependents[] where registered is falseOnce resolved, a dependant is just a patient with their own identifier, carried forward like anyone else's. The relationship matters for cover, which is 02 · Verify cover, but it makes no difference to identity.
The situations a front desk meets
There are six. In each one the mistake is resolving too late, resolving too often, or resolving with too little to go on.
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Reception, new patient | Someone presents for the first time at your facility | Look them up before you open a local file. Create the record first and resolve later, and you end up with two records for one person and no clean way to merge them. |
| Reception, returning patient | Someone you have seen before comes back | Do not re-resolve them by national ID. You stored the registry identifier the first time, so use it. This is the biggest single saving available at a busy desk. |
| Reception, a child or spouse | A dependant is presenting, often with no document of their own | Look up the person whose cover it is, then pick the dependant from their record, as above. |
| Triage or casualty | An unconscious or unidentified patient arrives | Treat first. Identity resolves on a temporary registration and is reconciled afterwards, so the lookup never blocks care. |
| Admission | An inpatient is being admitted | The identity must already be resolved. An admission opened against an unresolved patient produces a claim nobody can attach to a person. |
| Cashier or pharmacy | A bill or a dispense is being raised | Do not look up again. Carry the identifier forward from the desk. Re-resolve mid-encounter and the same patient ends up billed under two identities. |
The rule underneath all six is to resolve once per patient, as early as you can, and then carry the result.
When the registry is slow
The registry is a national system reached over a network, and sometimes it answers more slowly
than a person standing at a desk is willing to wait. Design for that rather than treating it as
an incident. The service answers 504 REGISTRY_TIMEOUT for any failure of the registry search,
not only a slow one, so a bad identifier type can arrive the same way. Retry once before you
treat it as an outage.
- 01Choose your own timeoutThree to five seconds, set by you rather than whatever your HTTP library defaults to, which is usually far too long for someone standing at a counter.
- 02Retry once, idempotentlyReuse the same lookup reference so the two attempts can be matched in logs and support. The service does not de-duplicate on it yet, so the registry is asked again.
- 03Cap the total waitOnce you are past your budget, stop calling and change the screen. Telling the operator you will follow up beats holding them on a spinner that never ends.
- 04Offer a pending pathLet the desk carry on. Take the details, open the encounter on a temporary identity, resolve in the background and reconcile when the registry answers.
- 05Cache for life, not for a sessionMost patients are returning patients, so most registry latency never reaches a user. One resolution per patient per lifetime removes most of this problem before any timeout tuning does.
Next
Back to 01 · Identify for the step itself, or on to 02 · Verify cover, where a resolved identity becomes a question about cover.
A complete brief for this step — the calls to make, what to persist, and every failure path to handle. Nothing on this page is assumed.