# The rail, end to end

  Cover in this country sits in two worlds, the national public payer and the private payers, and a
  patient can belong to both on the same day. The rail is one connection that reaches both.

## What the rail is

Behind a patient there may be the national public payer, a private insurer, an employer fund, or several
at once. Each of those has its own membership register, its own benefit rules, its own tariffs and
its own claim format. Reaching them yourself means an integration per payer, and a new one every
time a payer changes something.

The rail sits in the middle of that. You connect to it; it connects to them.

<Wire
  rows={[
    { call: "One connection, both worlds", does: "The national public payer and the private payers answer through the same calls, in the same shapes. Which of them is behind a given member stops being your problem, and stops being a branch in your code.", keep: "one integration" },
    { call: "The national registries, included", does: "Patient identity, practitioner licensing, facility records and the coded vocabularies everything is expressed in. You read them through the rail rather than integrating with each.", keep: "resolved identities" },
    { call: "The hard parts, absorbed", does: "Which fund pays, which tariff applies at your facility, whose balance is read, what needs approving, how a claim is assessed, how overlapping covers coordinate. All of it happens behind the calls you make.", keep: "your part stays small" },
  ]}
/>

Most of the work sits in the third row. At every stop the pattern is the same: you supply a
decision a human made, and the rail resolves everything that follows from it. You send the
identifier a patient handed over, the cover an operator chose, the clinician who treated them and
the items that were done. You do not rank payers, split funds, price against a contract or compute
what is left on a limit.

## What end to end means

One patient, from walking through the door to the facility's reimbursement landing in its bank
account, is ten labelled stops. Only nine of them are about the patient. `00` is how your
system gets onto the line in the first place, and it happens once at start-up rather than per visit.

| # | Stop | The question it answers | What you keep |
|---|------|------------------------|---------------|
| 00 | Authenticate | Who is asking, and from which facility? | an access token, and the facility headers |
| 01 | Identify | Who is being treated, who is treating them, and where? | `unique_patient_id`, plus the clinician's registration |
| 02 | Verify cover | Which cover pays, and what does it pay for here today? | `selection_ref`, and the billable units read against it |
| 03 | Consent | Can we prove they were present and willing? | an authorisation reference |
| 04 | Visit | Is the encounter open, and against which cover? | `visit_id` |
| 05 | Treat | What was found, what was done, and who else needs to know? | `diagnosis_id`, and a record written to the SHR |
| 06 | Preauthorize | Does this need approving before it may be done? | an approval reference and per-item approved amounts |
| 07 | Bill | What was actually done, and what does it price at? | line references, reservations |
| 08 | Submit | Is the claim complete enough to send? | `claim_id` |
| 09 | Reconcile | Did the money arrive, and against what? | a remittance matched to an invoice |

Every scenario you will meet is this sequence with different values in it. An outpatient visit, an
admission, an emergency, a dependant on somebody else's cover and a member with four active
schemes all run in the same order, with different answers. Once you know the order, each new case is a
variation on it rather than something to work out from scratch.

## What success looks like

Calling all ten stops does not make an integration finished. It is finished when the things below
are true, because each of them is a job that otherwise lands on a person every single day.

<BuildSequence
  steps={[
    {
      do: "No coded value is typed by hand",
      detail:
        "Every picker (identifier types, diagnoses, interventions/services, document types) is fetched from the terminology service in the right versions. Nothing is transcribed into a constant.",
    },
    {
      do: "A patient is resolved from what they handed over",
      detail:
        "An identifier and its type, including the cases that are harder than a card: dependants, minors, a member whose document does not match the register. One resolved identity carried forward.",
    },
    {
      do: "The cover is chosen by a person, and visibly",
      detail:
        "Every cover the member can use here is listed, somebody selects one, and the choice is recorded and changeable until the claim is submitted. The system never picks one on its own.",
    },
    {
      do: "Consent is proof, not a checkbox",
      detail:
        "Whatever modality the payer requires (a one-time code, biometrics, a guardian), it is collected through one flow and produces a reference the claim can carry.",
    },
    {
      do: "The price is yours, and it is checked while the patient is still there",
      detail:
        "The facility sets what it charges. Where a payer states a tariff for that item, the rail validates the line against it as the line is added, so a rate problem surfaces at the desk rather than as a rejection weeks later, when the patient has gone home and the correction costs a person instead of a keystroke.",
    },
    {
      do: "Claims and preauthorisations fail at entry, not at submission",
      detail:
        "Of everything here, this is the one worth building for. Your system catches what is wrong while the encounter is open, whether that is a missing document, an unmapped code, a benefit that does not cover this access point or a diagnosis the procedure does not support, and it says what is wrong and what would fix it. Every one of those caught at the desk is a rejection that never happens, and a correction that costs seconds rather than a follow-up.",
    },
    {
      do: "Decisions arrive without being chased",
      detail:
        "Preauthorisation and claim outcomes are delivered to a registered callback. Nobody polls or refreshes a screen waiting for an answer.",
    },
    {
      do: "Remittances match themselves",
      detail:
        "Payments land against the invoices they belong to automatically, and only the exceptions reach a human, as a short worklist rather than a reconciliation exercise.",
    },
  ]}
/>

If you want a single test: in a fully integrated system nobody's job is to re-enter, chase or
reconcile anything the rail already knows, and almost nothing reaches submission that the desk
could have caught.

The second half is what the errors are shaped for. Every error the rail returns names the stage that
can resolve it, so your interface can route a problem to the screen that fixes it instead of
reporting it where it was noticed. See [the error dictionary](/rail/reference/Errors).

## Three ways to read the sequence

Where the stops sit on the line, who talks to whom while a visit runs, and what each step hands the
next.

<Mermaid chart={`sequenceDiagram
    autonumber
    actor D as Front desk
    participant H as Your HMIS
    participant R as The rail
    participant X as Registries & payers

    H->>R: Credentials + facility
    R-->>H: Token
    D->>H: Identifier pair
    H->>R: Resolve the patient
    R->>X: Client registry
    X-->>R: One identity
    R-->>H: unique_patient_id
    H->>R: Covers for this member here
    R->>X: Coverage and contributions
    X-->>R: One entry per scheme per contributor
    R-->>H: Covers to choose from
    D->>H: Chooses a cover
    H->>R: Freeze it, then open the visit
    R-->>H: visit_id
    H->>R: The coded diagnosis, and the encounter
    R->>X: Shared health record
    H->>R: Bill the items that were done
    R-->>H: Priced lines
    H->>R: Submit the claim
    R->>X: Assessment
    X-->>R: Decision, later
    R-->>H: Callback, then remittance
    Note over H,R: Your side is decisions and items.<br/>Everything crossing to the right is absorbed.
`} />

<Mermaid chart={`flowchart TD
  A["00 · Authenticate"] -->|"token + facility"| B["01 · Identify"]
  B -->|"unique_patient_id"| C["02 · Verify cover"]
  C -->|"the chosen cover"| D["03 · Consent"]
  D -->|"an authorisation"| E["04 · Visit"]
  E -->|"visit_id"| T["05 · Treat"]
  T -->|"coded diagnosis, linked"| F["06 · Preauthorize"]
  T -.->|"the encounter, as FHIR"| S["Shared health record"]
  F -->|"approval + amounts"| G["07 · Bill"]
  G -->|"priced lines"| H["08 · Submit"]
  H -->|"claim_id"| I["09 · Reconcile"]
  G -.->|"invoice, not a claim"| J["eTIMS branch"]
`} />

If you find yourself holding a value and not knowing what it is for, it is almost always the
input to the step after the one you are on.

## Step 1 is three identities, not one

Almost every integration reads "Identify" as "look the patient up", builds that, and meets the
other two identities months later as claim rejections. A billable encounter eventually has to
assert three things, so it is cheaper to know that on day one.

<Wire
  rows={[
    { call: "The patient", does: "Who is being treated. Start here, because nothing else on the rail can begin until this resolves, and every later step takes it as input.", keep: "unique_patient_id" },
    { call: "The healthcare worker", does: "Who is treating them, and whether their licence permits it. Resolved when the clinician is chosen, re-checked at preauthorisation and billing.", keep: "registration number + regulator" },
    { call: "The facility", does: "Where this is happening. Already carried by your credential, and it scopes the rules, price included.", keep: "facility_code" },
  ]}
/>

The patient is the one to build first, and the only one that gates everything. The other
two are cheap to add early and expensive to add late. A clinician whose licence lapsed produces
a rejected claim days after the care was given, by which time the encounter is closed and the
patient has gone home.

All three resolve the same way, an identifier plus what kind of identifier it is, so the second
and third cost you a form each rather than a new mental model.
[01 · Identify](/rail/stops/Identify) covers all three.

## The clearest example of the division

A member may hold covers from several payers, be a dependant on some of them, and have overlapping
benefits across them. Working out how those interact is the rail's side of the line. Your part is to
list them, let somebody choose, and send that choice back.

## Why the order is the order

The sequence is not administrative preference. Each step is a precondition for the next,
and skipping one does not fail where you skipped it. It fails later, looking like a different problem.

Identify comes before eligibility because coverage is answered per person and per scheme, and
you cannot ask about cover you have not established exists.

Eligibility comes before consent because what you are asking the member to consent to depends on
what is being accessed.

Consent comes before the visit because the visit is bookended by authorisation. Opening an
encounter is a consent event in its own right.

The visit comes before billing because a line has to attach to something. Pricing is resolved live
against the cover frozen onto the visit.

Billing comes before submission because submission runs every completeness gate again, and a claim
assembled after the fact is assembled from memory.

Submission comes before reconciliation because payment matches on the invoice reference, not on the
member, the amount, or the date.

## The two reorderings

Elective care moves preauthorisation ahead of the visit. Approval is sought before the
patient arrives; the visit then opens against an approval that already exists.

Emergency care reverses the first two steps. Treatment begins before identity is
established, and identity is attached afterwards, with the claim carrying the correction.

Everything else about the spine holds in both cases.

## Where you are, always

Readers arrive in the middle, from a search result, a colleague's link or an agent's
citation, so every page in this section shows the spine with the current step lit. If you
have landed somewhere unfamiliar, the strip at the top of the page tells you what came
before it and what comes after.

## What drives the sequence at runtime

You do not hard-code the order. Every response carries `next_action`, naming the move and,
where relevant, the endpoint to call. Your client switches on that enum.

Hard-coding the sequence works right up until a step is legitimately skipped: an
already-granted authorisation, an auto-created reservation, a preauth that was not
required. Then it stops working. Reading `next_action` handles those cases without
you writing a single branch.

See [`next_action`: the contract](/rail/concepts/Next-Action) for the full enum.

**Next:** walk it end to end, starting at [Authenticate](/rail/stops/Authenticate).