02 · Verify cover

What this step is

01 · Identify told you who is in front of you. This step answers the money question, and it asks two separate questions to do it. Do not run them together.

Keeping them separate is what stops a member with nine covers waiting on nine benefit walks before anyone has asked which one they are using. The covers list asks each payer whether the member is current and carries no balances. Balances arrive with the tree, for the one cover that was selected.

The two are ordered by the handle rather than by good manners. The benefit tree is read against a selection_ref, and only covers/select mints one. There is no way to read the second before the first has answered.

The rule that makes it work is that a person is not covered. A person holds covers, and exactly one of them pays for a given selection.

Two things are worth knowing before the detail starts, because they decide how much of this you have to build yourself.

All three calls sit under /api/v2/patients/{unique_patient_id} and all three refuse to run without the facility headers: a call without X-Facility-Id and X-Facility-Id-Type answers 400 FACILITY_CONTEXT_MISSING, and a token claim does not stand in for them.

The four moves

There are four of them, and the split between the first two is the part that matters most.

1. 01List the coversEvery entitlement this member holds with each payer, with who contributes to it and how long it runs. It carries no balances, so it is light enough to render a chooser at once. covers.list
2. 02Select one, visiblyAn operator chooses. Do not auto-select silently. This is a financial decision, and nobody can audit a choice they cannot see. Send the
   Code

   cover_id
   back and keep the
   Code

   selection_ref
   .
3. 03Walk down to a billable serviceBenefit, then sub-benefit, then service line, one call per level. Follow next_action.type: filter_benefits goes one level deeper, anything else ends the walk on that node.
4. 04Read the balance on the nodeEvery node carries
   Code

   coverage
   . Where a payer reports a figure it is there; where it does not,
   Code

   known
   is false and both numbers are null. Null means unknown and is not zero. Read it before quoting an amount, because a limit may be shared with a pool that a sibling has already drawn on.

A missing balance is not a gate. It means the payer did not report one, and the visit stop checks again with whatever it knows then. A balance of zero is different: that node comes back blocked with blocked_by: "BENEFIT_EXHAUSTED" and offers no next step.

If you only remember one thing: the cover is chosen once, explicitly, and everything priced afterwards hangs off that choice.

What it looks like at the desk

Three ways to look at the step: the screens, the sequence and the branch points.

A member can hold many covers, and be a dependant on some of them

This is the part that surprises people, so it is worth stating plainly before any payload.

So the unit is usually the payer, and a payer's schemes are inside the cover rather than beside it. What multiplies rows is contributors: a dependant can hold an entitlement under each parent's policy, and each of those is a separate cover with a separate cover_id.

membership.member_type says which case you are in, as the payer states it. membership.principal_relationship is the member's relationship to the contributor, and is SELF for the principal. On a dependant cover, membership.principal_contributor names the person whose cover it is: name, id_number, id_type, cr_number, employment_type and employer, with the identifiers masked. It is absent when the source named no contributor, which is most covers. Store it with the encounter: every audit conversation about a dependant's claim opens with "under whose cover?".

The identifiers in the response are masked. membership.member_identifier shows a short leading fragment and hides at least its last four characters, and cover_id is a hash that carries none of it.

On screen, that looks like this.

Members a payer knows but was not asked

known_memberships[] is a separate array on purpose. It lists payers the master index files this member under that no source answered for. Each carries a note saying to confirm with the payer directly. They are not covers, they cannot be selected, and covers/select would not find one.

An empty covers[] with a non-empty known_memberships[] is the member who holds a valid card with a payer this rail did not ask. Show it as "ring the payer", not as "no cover".

is_alive sits at the top of the response because it is a fact about the person, not about any one cover. It is true, false, or null when the source that carries it could not be reached, and null does not mean deceased.

There is no ranking, so do not build one

A member with several covers is not a puzzle with a correct answer. Pick any of them and you see the benefits that cover supports. The covers frequently overlap, since the same eye-health benefit can exist on two of them, so there is nothing to sort and no precedence to apply.

So the chooser has one job, which is to show what each cover is and who contributes to it, then let a person decide. Group rows by payer if that helps the eye, but do not pre-select across payers and do not imply an order that the rail does not enforce.

A dependant can be covered under more than one principal at the same time. A child whose mother holds one fund and whose father holds another comes back with covers from both households. One of them is used for a given selection, and which one decides the tariff, the limits, the required documents and the combination rules, so the choice is not cosmetic.

Benefits are also filtered by member type. Principal, spouse and child see different things on the same scheme, so do not cache one member's benefit list and reuse it for a relative. The tree is read per selection, and each selection is one member's cover.

The household behind the covers

A cover usually belongs to a household rather than to a person. That is where the extra covers on the previous screen come from: a member appears on their own cover as principal, and on a relative's cover as a dependant. One person, one day, two entries.

The covers response does not list the household. Reading it is a separate call, GET /api/v2/patients/{unique_patient_id}/metadata?consent_ref=…, and it returns the unmasked identity, contacts and dependents[], so it is gated on a verified pii_access consent for that patient. A dependant the index knows comes back with a unique_patient_id of their own, and their covers are listed by calling covers with that id. A dependant the index does not yet hold is returned unregistered rather than dropped.

Where a limit applies to a household, a relative's admission may have drawn on the same pool. The node's coverage.shares_parent_limit says when the amount left belongs to a pool rather than to the line.

Reaching a dependant through a principal is covered at 01 · Identify.

One cover, or several

Everything so far has assumed you pick a cover and move on. That is the common case and it is worth stating separately from the harder one, because the two behave differently and the difference decides who pays.

The single-cover case

One usable cover. Select it, and the rail writes a FHIR Coverage for that patient to the clinical store, keyed on the cover_id, and returns that record's id as the selection_ref. Selecting the same cover again updates the record and returns the same selection_ref, so a retry after a timeout is safe.

Three things about that record are easy to misread.

Selection re-asks the payers before it writes, because this is the point of commitment: a cover that lapsed between listing and selecting must not be the cover a visit opens against. That is why facility_patient_no has to be sent again if the list took one. A cover from a source keyed on that number cannot be confirmed without it, and the selection is refused as a stale handle.

The multiple-cover case

A member may hold several usable covers at once: their own, plus one or more where they are a dependant on somebody else's. All of them may be valid, and only one pays for a given item.

Each cover is selected on its own and gets its own selection_ref. Which one an item draws on is settled at the visit: a service line names the cover it draws on, and that cover has to be one the visit's selection holds, otherwise the visit stop answers 409 COVER_NOT_IN_SELECTION. A cover outside it needs its own selection and its own consent. See Visit for how lines name a cover.

Do not model the cover as a single value on the visit. A provider who bills two contributors in one encounter and cannot see which line went where will not be able to answer a query about either, so carry the cover_id and the contributor on each line you raise.

Once a cover is chosen

Everything above answers which cover pays. The second half of the question, what that cover pays for, is a tree you walk, and it is long enough to have its own page.

The calls

Three calls answer the cover question, and they run in order: list, select, then walk. Each is v2, each needs the facility headers, and each answers with its own next_action naming the one that follows.

Open 02 · Verify cover in the Rail API reference to read or run them, with a Try it console for when the sandbox is live.

List the covers

{
"unique_patient_id": "2029090000000046",
"is_alive": true,
"covers": [
  {
    "cover_id": "SHA:Qm3xT9vKp2LrYw8d",
    "source": "SHA",
    "payer_code": "2029",
    "payer_name": "Social Health Authority",
    "membership": {
      "member_identifier": { "type": "CLIENT_REGISTRY_NO", "value": "CR56********" },
      "member_type": "PRIMARY",
      "principal_relationship": "SELF"
    },
    "schemes": [
      { "code": "1", "name": "UHC",  "policy_number": "SHA-POL-0001", "valid_from": "2024-10-01", "valid_to": "2034-09-30", "status": "ACTIVE" },
      { "code": "2", "name": "SHIF", "policy_number": "SHA-POL-0002", "valid_from": "2024-10-01", "valid_to": "2026-09-10", "status": "ACTIVE" }
    ],
    "valid_from": "2024-10-01",
    "valid_to": "2034-09-30",
    "status": "ACTIVE",
    "selectable": true,
    "as_of": "2026-08-14T09:12:40Z"
  }
],
"known_memberships": [],
"unavailable": [
  { "source": "SLADE", "reason": "PAYER_UNREACHABLE", "message": "SLADE could not be reached. Covers held there are not in this list." }
],
"next_action": {
  "type": "select_cover",
  "method": "POST",
  "endpoint": "/api/v2/patients/2029090000000046/covers/select"
}
}

curl -X GET "$RAIL_BASE_URL/api/v2/patients/{unique_patient_id}/covers" \
  -H "Authorization: Bearer $RAIL_TOKEN"

The response is the struct itself, with no message wrapper around it. Read it this way.

The next_action is a select_cover with method and endpoint and, only when you sent facility_patient_no, a requires entry naming it: "the same number sent to this list". It is the same {type, method, endpoint, requires[], then} shape every stop uses, described in Next Action.

Failures on this call:

A payer failing on its own is not an error. It appears in unavailable[] with a source, a reason (PAYER_UNREACHABLE unless the source said more) and a message, and the call is still a 200.

Select one

{
"cover_id": "SHA:Qm3xT9vKp2LrYw8d"
}

{
"selection_ref": "cov-8f3a21c4",
"unique_patient_id": "2029090000000046",
"cover": { "cover_id": "SHA:Qm3xT9vKp2LrYw8d", "payer_code": "2029", "status": "ACTIVE", "selectable": true },
"selected_at": "2026-08-14T09:14:03Z",
"next_action": {
  "type": "check_eligibility",
  "method": "GET",
  "endpoint": "/api/v2/patients/2029090000000046/eligibility/cov-8f3a21c4/benefits"
}
}

curl -X POST "$RAIL_BASE_URL/api/v2/patients/{unique_patient_id}/covers/select" \
  -H "Authorization: Bearer $RAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cover_id": "SHA:Qm3xT9vKp2LrYw8d" }'

The body is cover_id and, optionally, facility_patient_no. Nothing else is read. There is deliberately no cover payload: a client that sent back the scheme, the window and the status could select a cover the payer never offered. A scheme_id, or a facility identifier, is ignored if sent, and a facility identifier never belongs in a body: the facility travels in the headers. The cover in the response (abbreviated above) is the cover as the payer described it at the moment of commitment, which can differ from the list, and selected_at is when the record was written.

Failures on this call:

COVER_NOT_FOUND and COVER_NOT_SELECTABLE mean different things at a desk. The first says the list has moved on and should be fetched again. The second says the cover is real and unusable today, and the reason is in detail.

Walk the tree

The response, the walk rules and the errors are on the next page, What a cover pays for. The handle is the selection_ref, not an eligibility reference: v2 has none. Reading the tree takes no consent proof.

The next_action values you will meet here

Public-officer and teachers' covers are a different rule set

They look like another scheme in the list. They are closer to a parallel rule set, and four differences matter enough that treating them as a variation produces claims that cannot be paid.

What you keep

What breaks here

One pattern runs through most of that list. The response said so and the screen did not. The contributor, the access point, the balance, the preauth flag and the payer's own reason are all present at this stop, and every one of them, dropped here, becomes somebody else's problem later.

Errors

These are the codes this stop's three calls emit, taken from the service. Where a cause is not a domain failure, such as an unreadable body, error is the status text instead of a code.

What carries forward

Next: 03 · Consent. With a cover chosen, the member has to confirm they are present and willing.