The integrator's view
Every call on this rail is made while one person stands in front of another, waiting.
Everything below elaborates this sentence.
Why this page exists
Endpoint documentation tells you what a payload contains. It does not tell you which screen the payload fills, who is waiting on it, or what happens to that person when it fails.
That is what this page covers. Everything below runs in three lanes: the desk, which is what a person sees; your system, which is what you render and call; and the rail, which answers.
The screens below are low fidelity on purpose. They are an argument about what has to be on screen at each moment, and which field puts it there, not a UI to copy.
The shape of a visit
Start with the shape, before any screens. A visit behaves less like a form submission and more like a conversation with pauses in it, and the pauses are where integrations get designed badly.
Note what the desk does and does not do. It presents an identifier and it picks a cover. Everything else is your system and the rail talking. If your design has the operator making decisions at any other point, you have moved work onto a person who does not want it.
Screen 1 · The front desk
The first screen has one job, which is to turn a human being into an identifier. It usually fails because the identifier type was never captured alongside the value.
GET /concepts/?system=IDENTIFIER-TYPESbiodata.name, dob, genderconsent.receiptcontacts.phones[].verifiedWhen this screen fails, a conflict is not an error to retry. It means the identifier matched more than one person, so the screen should ask for a second identifier instead of showing a red box. Design that path, because you will use it.
Screen 2 · Choosing a cover
This is the screen where benefit coordination becomes real. A member with several covers needs a person to choose between them, and that person needs enough to choose with.
unique_patient_idcovers[]covers[].schemes[]Screen 3 · Consent
This is the screen you mostly do not build. Which proofs are legal at that moment is resolved from the member, the facility, the payer and the benefit, so what you render is whatever the rail returns, in a frame.
embed_urlexpires_atScreen 4 · Billing
Your billers live in this screen. Two things belong on it that are routinely left off: the lines that are waiting, and the cover being billed against.
cover + visit_idlines[].statusrequiredDocumentspreflight.reasons[]The pauses, and how to design for them
Three moments in the journey are asynchronous. Each needs a state in your system, not a spinner.
Awaiting approval is a state you persist. Honour the polling interval, and let a callback settle it if one arrives first. A user should be able to close the browser.
Returned is not a rejection but a request that is waiting on you. A returned item that nobody resubmits is the second commonest reason money never arrives.
Awaiting payment is the gap between approved and paid. Model it explicitly, or your finance team will build a spreadsheet to do it for you.
What the desk should never be asked
A short list, all of it learned the expensive way:
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Identity | "Which ID type is this?" | The type should come from the scan or the picker, not from the operator's judgement. |
| Identity | "Whose licence is on this line?" | The clinician is an identity too, resolved by regulator plus registration number. Picked from a typed list, it is only a name with nothing behind it. |
| Consent | "Should we use fingerprint or a code?" | The permitted factors are resolved for you. Offering a choice invents one that may not be legal. |
| Billing | "Is this covered?" | Items were filtered to what is billable at eligibility. If it is on screen it is billable; if it is not, say why. |
| Submission | "Why was this rejected?" | Every reason carries a fix_stage. Route them to the screen that fixes it instead of showing the message. |
Next: Ride the rail · or read benefit coordination