Referrals, samples and one authentication
A patient authenticated at the dispensary that referred them should not have to authenticate again at the hospital they were referred to. The proof travels with the referral.
Everything below elaborates this sentence.
Hub and spoke, without building hub and spoke
A referral network is normally a project: agreements between facilities, an integration per partner, a shared directory, a way to move documents. Every new spoke is new work.
On the rail it is a call. Both facilities are already connected, both are already resolved against the facility registry, and the clinical record is already in a form the other side can read. Referral is what those things add up to.
| Call | What it does | What you keep |
|---|---|---|
You refer | Name the receiving facility and the service you want. The clinical record goes with it. A referral is not a letter asking them to start again. | referral_id |
They see it before the patient arrives | An inbound referral is in their queue with the diagnosis, the investigations already done and the results already back. | their inbox |
They accept, and the visit opens | Acceptance opens the receiving visit against the authorisation the source took. The patient walks in already known. | visit_id |
Refer
Refer onward, carrying the record and the authorisation taken here.
include_clinical: true is the field that decides whether this is a referral or a note. With
it, the receiving clinician opens the patient and sees the encounter, the conditions, the
observations and any results already returned. That is the difference between a hub that
repeats the workup and one that continues it.
Referrals sent to this facility, with the record and the authorisation attached.
Accept or decline, and open the receiving visit against the source authorisation.
Accept the referral before you open a visit. A visit opened against an unaccepted referral is
refused with REFERRAL_NOT_ACCEPTED. Acceptance is what binds the source authorisation to the
new encounter, so skipping it sends the patient back to authenticate.
One authentication, at the facility they were standing in
Build the workflow around this feature, because it is the one patients notice.
Consent on the rail is proof that a member was present and willing. Ordinarily it is taken where the care happens. On a referral that rule would mean a patient authenticates at the dispensary, travels to the county hospital, and authenticates again for the same episode, often returning a second day because the biometric device was down or the phone that receives the code was left at home.
- 01Take the authorisation once, at the sourceThe patient is standing in front of you. Whatever modality the payer requires (a one-time code, biometrics, a guardian) is collected here, at [03 · Consent](/rail/stops/Consent), and produces an authorization_ref.
- 02Send it with the referralauthorization_ref travels on the referral. The response echoes back where it was authenticated, whether the destination will honour it, and when it expires.
- 03The destination opens against itAccepting the referral opens the receiving visit bound to that authorisation. The patient does not give consent a second time, on a second device, at the end of a second journey.
- 04Show the patient the window, at the sourceThe authorisation has an expiry. Tell the patient when they are referred, not when they arrive. This is the one failure mode the design does not remove.
If the patient arrives after the window has closed, the destination gets
REFERRAL_AUTH_EXPIRED. That is a prompt to re-authenticate there, rather than a rejected
referral. The clinical record and the acceptance both stand.
Samples travel the same way
A specimen sent to a hub laboratory is an order with a journey attached. The order says what to do; the sample record says what physically moved, and lets both ends see where it is.
Send a specimen against the order that asked for it.
| Call | What it does | What you keep |
|---|---|---|
The sample is tied to the order | Not to a courier manifest. The result comes back against the order, so the requesting clinician sees it in the patient's record rather than in an email. | order_id |
Cold chain is declared, not assumed | A specimen that must stay cold says so, and a hub that cannot honour it declines on receipt rather than running a test on a degraded sample. | cold_chain |
Rejection is a state with a reason | The reason reaches the sender (haemolysed, insufficient, unlabelled), who can recollect while the patient may still be reachable. | the reason |
A spoke that can send samples can offer tests it cannot perform. That is the commercial argument for the referral feature, and it is the same three calls as everything else on this stop.
What breaks here
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Treat | "The patient was sent back to authenticate again" | The receiving visit was opened directly instead of through referral acceptance, so nothing bound the source authorisation to it. |
| Treat | "They arrived and the authorisation had expired" | The window was never shown at the source. Surface the expiry when the referral is written, on the patient's copy. |
| Treat | "The hospital started the workup from scratch" | include_clinical was false, so the referral carried a reason and nothing else. |
| Treat | "The result went to the hub, not to us" | The sample was sent without the order it belongs to. Results route by order, not by facility. |
Errors
| HTTP | error | When |
|---|---|---|
| 409 | REFERRAL_NOT_ACCEPTED | A visit was opened against a referral nobody accepted. |
| 409 | REFERRAL_AUTH_EXPIRED | The source authorisation's window closed before arrival. |
| 403 | CLINICAL_CONSENT_MISSING | The patient's proof does not cover sharing the record onward. |
Everything a referral carries was recorded once, as clinical data. The same recording is what lets the rail generate the documents a claim needs, instead of somebody typing them.