# 01 · Identify This is the step where you work out who is in front of you, using whatever documentation they carry. The patient first, then whoever treats them. Each becomes an identity the whole health system agrees on. ## What this step is Someone arrives holding a national ID, a birth certificate, a refugee ID or a membership number. Whatever it is, this step turns it into the one identifier the health system knows them by. Someone tells you who they are, and this step checks that against a national registry and gives back one official answer. Patients are checked against the client registry, clinicians against the health worker registry. It is the same question each time, asked of whichever register is authoritative for it. The patient's identity is the one everything after this step keys off. The clinician's is what makes the claim defensible once care has been given. The rule that makes it work is that an identifier without its type is not an identifier. It is only a number, and a number resolves to nothing. Three identities get resolved here: the patient, the clinician treating them, and the facility they are in. The patient is the one that starts everything, so the rest of this section is about them. The other two follow further down. ### The four moves of a lookup The way you resolve a patient is the patient lookup, and it takes four moves: The operator chooses what they are holding: National ID, birth certificate, refugee ID. That list is{" "} fetched from the terminology service , rather than a constant in your code. ), }, { do: "Send the pair", detail: "The identifier's value and its type travel together, in one call, inside your facility context.", }, { do: "Read back one identity", detail: "The registry resolves the pair to a single record and returns the identifier the health system knows this person by, with minimal masked details so the operator can confirm the right human.", }, { do: "Store it and carry it", detail: "Save that identifier against your own patient record. Use it for every later call in this encounter, and for every future visit by the same person.", }, ]} /> Remember this much: an identifier travels with its type, and what comes back is stored once and reused forever. ### What it looks like at the desk Three ways to look at the same step: the screen an operator sees, the branches they can land in, and which system answers whom. Always two inputs. A single free-text box is the commonest cause of a "patient not found" for a patient who is very much in the registry.} /> Filled in, with the values a real desk would see: The identifier you type is not the one you keep. You type a National ID and you store what the registry returns.} /> >H: Picks document type, enters number H->>R: Lookup (type + value + facility context) R->>C: Resolve the identifier pair C-->>R: One record, or none, or several R-->>H: unique_patient_id, masked details, next_action H-->>D: Confirm the human, then continue Note over H,R: Store unique_patient_id now.
A returning patient is never re-resolved. `} /> B{Registry answered?} B -- "No, timed out" --> T["Pending, retry once,
then let the desk continue"] B -- Yes --> C{How many records matched?} C -- None --> N["Not found
Re-check the TYPE first"] C -- "More than one" --> X["Conflict
Ask for a second document"] C -- Exactly one --> D{Is the person alive?} D -- No --> E["Stop. Escalate clinically."] D -- Yes --> F["Identity resolved
store unique_patient_id"] F --> G["Carry it to 02 · Eligibility,
where cover is asked"] `} /> The request is the pair and nothing else. Facility travels in headers, on every call. There is no consent block. Proving the member agreed is [3 · Consent](/rail/stops/Consent). This call resolves an identity; it does not read a record. #### What is redacted, and what is not `identifiers[]` is the array the operator actually decides on. Each value shows enough to recognise and not enough to reconstruct. The reveal is bounded so that at least the last four characters of any identifier stay hidden, which stops the response becoming a guessing oracle. Internal identifiers are absent rather than masked, because a masked internal id still tells a caller the record exists in a system they have no business knowing about. | Value | What comes back | |---|---| | Name | First name in full, later names keep first and last letter: `Wanjiru Mwangi Muturi` → `Wanjiru M****i M****i` | | National ID | First 4: `33121466` → `3312****` | | Phone | `+254700123848` → `+254700****848` | | Email | Local part masked, domain kept: `roy.thande@example.co.ke` → `roy***@example.co.ke` | | Registry / scheme identifiers | At most 4 leading characters: `CR6154087394882-8` → `CR61*************` | | `unique_patient_id` | Raw. The one value you store is the one value not hidden | | `date_of_birth` | Raw. Masking it left too little to recognise a person by | Two habits follow. Do not mask again on top of this, or you will hide the very characters an operator confirms against. And do not assume masking preserves length: name masking does, phone masking does not. #### Try it Or run it directly. Set a token with Set API Token in the header, then open [`patient.lookup` in the reference](/rail-api#tag/01--identify/post/api/v2/patients/lookup) for the parameters, both failure bodies, and a Try it console for when the sandbox is live. ```bash curl -sS -X POST "$RAIL_BASE_URL/api/v2/patients/lookup" \ -H "Authorization: Bearer $RAIL_TOKEN" \ -H "X-Facility-Id: FAC-2029" \ -H "X-Facility-Id-Type: fr-code" \ -H "Content-Type: application/json" \ -d '{ "identifier": { "type": "NATIONAL_ID", "value": "33121466" } }' ``` #### The two answers that are not a 200 A `404` means re-check the type before re-typing the number. A `409` is a prompt rather than a failure, and it carries what the desk needs to act: ```json { "error": "IDENTIFIER_CONFLICT", "message": "National ID 33121466 matches 2 records. Ask for a second document.", "path": "identifier.value", "fix_stage": "identify", "detail": { "match_count": 2, "candidates": [ { "biodata": { "name": "Wanjiru M****i M****i", "gender": "MALE" }, "identifiers": [{ "type": "CLIENT_REGISTRY_NO", "value": "CR61*************" }], "contacts": { "phones": [{ "value": "+254700****848", "verified": true }] } }, { "biodata": { "name": "Wanjiru M****a K****u", "gender": "MALE" }, "identifiers": [{ "type": "CLIENT_REGISTRY_NO", "value": "CR77*************" }], "contacts": { "phones": [] } } ], "disambiguate_with": ["CLIENT_REGISTRY_NO", "PASSPORT_NO", "BIRTH_CERTIFICATE_NO"] } } ``` A candidate carries no `unique_patient_id`. Until the operator has disambiguated, handing it over would let a caller resolve a person by guessing, which is the whole reason the answer is withheld. `disambiguate_with` names the types that would actually separate these two records, which is more use than "collect a second identifier". That covers one adult with one document. A child with no document of their own, the six situations a front desk actually meets, and what to do when the registry will not answer. ## Three identities, not one A claim is never an assertion about one person. Every claim eventually has to say: *this person, treated by that clinician, at this facility.* That is three identities and three national registries, and they all resolve the same way, with an identifier plus what kind of identifier it is. What matters more than the count is the order you build them in. Resolved at the front desk, before anything clinical or financial happens. Nothing else can start without it: there is no cover to select, no consent to take and no visit to open for someone the registry has not named. Keep{" "} unique_patient_id. ), }, { do: "Then · the clinician", detail: ( <> Resolved when someone is chosen to deliver care, later in the encounter, and possibly more than once as staff change. It does not block the patient being identified, but it does block a defensible claim. Keep the{" "} registration number and the regulator that issued it. ), }, { do: "Always · the facility", detail: ( <> You never resolve this one. Your credential already carries it, and every call above is made inside it. Keep facility_code set once in your HTTP client rather than at each call site. ), }, ]} /> Build them in that order. Nothing works without the patient. The clinician is what turns care already given into a claim that survives review. The facility is configuration rather than workflow. Most integrations stop after the first, because the first is what unblocks a demo. The cost shows up weeks later, in a rejection that names a practitioner instead of a patient. A patient is a number plus its document type, a clinician a number plus its regulator, a facility a code plus the registry it came from. Learn the pairing rule once and the other two cost you a form each. That is why this page teaches the patient in full and then moves fast. Part A is the lookup you have just read. Parts B and C follow. ## Why this step exists Everything downstream keys off one value, `unique_patient_id`: cover selection, eligibility, authorisation, preauthorisation, reservation, billing and claims. This step is where that value comes from, and it is the only place it comes from. Lookup is kept separate from eligibility on purpose. A member holding three covers should not wait on three balance checks before anyone has asked which cover they are using today. So this call stays light, with enough to render a chooser and nothing that needs a balance. Consent is not asked here. Resolving an identity is not the same as reading a record, and the two are separated on purpose: proving the member agreed is [3 · Consent](/rail/stops/Consent), once a cover is in view and there is something to consent *to*. What this call returns is minimal and masked, enough to confirm you have the right human in front of you without handing over the record. ## The call Two calls make this step. One tells you which document types are currently accepted, the other resolves the pair. Both live in the reference, with every parameter, every response code, and a Try it console for when the sandbox is live. Open [**01 · Identify in the Rail API reference**](/rail-api/01-identify) to read or run them. The sidebar there is this same rail, 00 through 08, so the stop you are reading and the endpoints you are calling stay in step. Connect once with the credentials widget in the header and every call on that page becomes runnable. The document types are not part of the rail's API at all. They are a coded list on the terminology service, and this is the call: Three things the reference will not tell you, which is why this page exists. ## What you keep `unique_patient_id` is the value that ties the rest together. Store it against your own patient record the first time you see it. Everything after this step takes it as input, and re-resolving somebody you have already resolved is the largest source of avoidable delay at a front desk. Keep `lookup_ref` too, for the length of the interaction. It is the audit handle for this resolution, and echoing it on a retry de-duplicates the attempt rather than recording a second one. ## A · The patient Covered above: an identifier pair resolves to one registry identity, and every later call hangs off it. One detail belongs here. The lookup also returns masked verified contacts, the phone and email the member has actually confirmed. Those are the channels a one-time code goes to at [3 · Consent](/rail/stops/Consent). When someone says "the code never arrived", start here. An unverified channel is a dead end rather than a delay. One habit is worth more than the rest: never store a name as free text where the registry gives you an identifier. A typed name is only a label. The registry identifier is evidence, and evidence is what you get asked for months later. ## B · The healthcare worker Every billed line carries the clinician who performed it, their licence, and the body that regulates them. Resolving that here makes the line defensible later, and it is the last cheap moment to discover a lapsed licence. The question is the same one asked of the patient, who are you and does your paperwork hold up, and it is answered the same way: a number plus what kind of number it is. The regulator is half of a registration number, exactly as a document type is half of a patient identifier. It happens at a different moment, though, and usually on a different screen: the patient is resolved at the desk, the clinician when care is assigned. The regulator picker, what a licence verdict looks like when it holds and when it does not, cadres and specialities, and the four things the health worker registry buys you, with the screens, the sequence and the workflow. ## C · The facility Facility resolution is real. The registry decides the tariff variant, whether a benefit is billable at your site at all, and which consent factors are offered. You do not call it to get started, though: your credential already carries a facility context, and every call on the rail is made inside it. The rest waits until the facility contracts settle. Two rules are safe to build on now. Never store a facility level. Read it each time, because levels and contracts change, and a stored level produces mispricing that is very hard to trace back. And expect a newly onboarded facility to be briefly absent, which is a transient to retry rather than a bug to report. ## Proving it is the same person Resolving an identifier tells you a record exists. It does not tell you the person holding the document is the person in the record. That proof happens at [03 · Consent](/rail/stops/Consent), where you send a purpose and the rail [decides the factor](/rail/stops/Consent#which-factors-a-facility-can-even-offer). What is possible there is decided here, by flags this step returns, so it belongs on this page. There are two paths, and they differ in kind rather than in degree. The adult match rate is around 70%. That number changes what you are building: a fallback used 3% of the time is an error screen, and a fallback used 30% of the time is a main path. Design the one-time-code route as a first-class flow with its own screens rather than an exception handler behind a failed scan. Because minors are enrolled rather than matched, not every desk is an enrolment point. If your integration serves paediatrics, find out whether the sites you are deploying to can enrol before you assume the fingerprint path exists for them at all. ## What breaks here Identity failures rarely announce themselves where the mistake was made. They surface later disguised as something else, usually as "the patient's fault" or "the payer's fault". **Patient identity** **Clinician identity** Two patterns account for most of those rows. The first is an identifier sent without its type: a patient number missing its document type, a registration number missing its regulator. The second is a state that exists in the API but not on the screen: a conflict, an unusable cover, a request nobody has sent yet. Neither is hard to fix, and both are expensive to find at a claim. ### Errors | HTTP | `error` | When | |------|---------|------| | 404 | `MEMBER_NOT_FOUND` | The identifier does not resolve to any registry record. | | 409 | `IDENTIFIER_CONFLICT` | It matches more than one record and cannot be disambiguated, so collect a second identifier. | A 409 is not a failure to retry. It is a prompt to ask the person at the desk for something else. ## What carries forward You leave this step holding three things. Each is an input somewhere later, and losing one means coming back for it, usually at the worst moment. The rail tells you where to go next. Every response carries `next_action`: switch on its `type`, then use the `endpoint` it hands you instead of building one, because it already carries the identity you just resolved. ```json "next_action": { "type": "select_cover", "endpoint": "/api/v2/patients/SIL-UPI-0091774/covers" } ``` Constructing that URL yourself works right up until a path changes. Reading it from the response never breaks, and it lets the sequence be reordered without touching your code. The full contract is at [next_action](/rail/concepts/Next-Action). **Next:** [02 · Verify cover](/rail/stops/Entitle). With an identity resolved, the question becomes which cover pays. {`You are integrating an HMIS with the Savannah unified payer rail. Task: implement step 1 of 8, Identify. Three identities are resolved here. A · THE PATIENT Fetch the accepted document types first, and cache them by version: GET /api/v1/terminology/concepts?code_system=IDENTIFIER-TYPES&version=serving Then resolve the person by identifier pair (value + type): POST /api/v2/patients/lookup { "identifier": { "type": ..., "value": ... } } Send X-Facility-Id and X-Facility-Id-Type on every call. Set them in the HTTP client. Do NOT send a consent block here. Identity resolution takes no consent; proving the member agreed is stop 03. Persist from the response: unique_patient_id // the thread; every later step takes this as input lookup_ref // echo it on a retry so the attempt is de-duplicated contacts // masked; these are the channels consent will use later Treat unique_patient_id as opaque: store it, send it, never parse it. Everything masked in the response is already safe to render. Do not mask it again, or you will hide the characters the operator confirms against. On 409, read detail.candidates and detail.disambiguate_with and ask for one of those document types. A candidate never carries a unique_patient_id. B · THE HEALTHCARE WORKER Resolve the attending clinician by regulator + registration number. The regulator is part of the identifier: KMPDC, Clinical Officers Council, Nursing Council of Kenya. Check licence status live and refuse a suspended or lapsed practitioner at selection time. Do not attach them and discover it at billing. Persist the registration number and its regulator on the encounter. Where an intervention needs clinical sign-off, request approval and model these states explicitly: not sent, pending, approved, declined. Provide a way to re-check; the answer arrives out of band. C · THE FACILITY Do not call for this. Your credential carries the facility context; set the facility headers once in your HTTP client rather than at individual call sites. Never store a facility level. Read it, because it changes and a stored level produces mispricing. PROVING IDENTITY (decided here, exercised at Consent) Adults are matched against the national biometric database; expect roughly a 70% match rate and treat the one-time-code fallback as a MAIN path with its own screens, not an error handler. Minors aged 7-17 have no national record: they are enrolled at the point of care, and not every site can enrol. Do not assume a fingerprint path exists for paediatrics. Carry forward the flags this step returns (biometric enrolment and OTP eligibility) rather than re-deriving them at Consent. RULES - An identifier is always a pair. Never send a bare number: a patient identifier without its type, or a registration number without its regulator, is the commonest false "not found". - Never hard-code a coded list. Fetch, cache by version, filter to active for pickers. - Never store a patient name as free text where a registry identifier exists. - Mask names, identifiers and contacts on screen. - Handle a conflict by prompting for a second document, not by retrying the same call. - A resolved patient with unusable cover is not a lookup failure: surface the reason and the possible solution, and let the encounter proceed as cash or on another cover. - Every response carries next_action. Switch on next_action.type and take the endpoint from the response rather than constructing it. Do not hard-code the sequence.`}