Copy page

The rail

What a cover pays for

This page picks up where 02 · Verify cover leaves off. That page answers which cover pays. Once a cover is selected, this one answers what it pays for, here, today.

Nothing below works without a chosen cover. The tree is resolved per member and per cover, so the same query with a different selection comes back different.

The next three views show the same structure: the screens an operator works through, the shape itself, and the calls behind them.

Whichever view you read, two things matter more than the levels themselves.

Balances are not a level of the tree. They are a separate question you ask about a node. Take the benefit code, or the procedure code where the payer tracks it that finely, pass it to the balance call, and you get what is left if that payer exposes it. Walking further down will never tell you anything about a balance.

Fund, access point, tariff and preauthorisation are not levels either. They are attributes that hang on whichever level the payer chose to attach them to. That is the part that trips people who have integrated one payer and assume the next behaves the same way.

The same rule can live at different depths

Of everything on this page, this is the part to hold on to, and it is why a hard-coded traversal breaks on the second payer you integrate.

So "does this need preauthorisation?" has no fixed home. Resolve the attribute against the whole chain, from the benefit down to the node you have selected, and take the most specific value you find. A traversal that only reads the leaf misses the insurer that declared it at the top, and one that only reads the benefit misses the scheme that varies it per procedure.

The same is true of access point, of document requirements, and of combination rules.

You walk it one level at a time

No call returns the whole tree, and that is not a limitation to route around. The tree is too large to hand over, and the national scheme's procedure list alone runs to thousands of codes.

So every level takes the code chosen at the level above it — passed to the same route, as parent_code, rather than to a route of its own.

1. 01Ask for the benefits on the chosen coverThe call with no parent_code. This is the only level you can ask for without already having a code in hand.
2. 02Pass the benefit code as parent_codeYou get its categories. Read what the benefit itself declared before you go further, because some payers have already answered your question here.
3. 03Pass the category code as parent_codeYou get the billable procedures, each with its own attributes, which override anything inherited.
4. 04Pass the procedure code as parent_codeWhere a payer exposes them, you get services, protocols and items. Many payers stop above this, and that is normal.
5. 05Ask the balance separatelyA sideways question rather than the next step down — and one the rail does not yet answer against a selection. See below.

Because the depth is a filter rather than a path, a client that stops when a level comes back empty is already correct for every payer. One that hard-codes four calls is correct for exactly the payers it was written against.

That has three consequences for the picker you build.

Take the depth from the response instead of assuming it. One payer's tree ends at the procedure, another carries services and drugs below it. Follow what comes back, and offer a select action on any node with no children.

A returned list may already start below the top. Because the tree is large, some responses answer at the category or sub-procedure level rather than at the benefit, depending on the payer and how the question was asked. Read the parent codes on every node and rebuild the chain rather than trusting position in the response.

Search has to cross levels. A clinician looking for "dialysis" does not know which benefit it sits under, and drill-down on its own will never get them there. Pair the walk with a search that returns leaves and shows the path above each hit, so selecting a search result still gives you the resolved chain.

One shape, several vocabularies

The words change per payer while the structure stays the same, and the rail normalises to the left-hand column.

On the rail	SHA calls it	Others may call it
Benefit	Benefit (SHA-07, PMF-07)	Package, category, class
Sub-benefit / category	Sub-benefit, or "sub-package" (SHA-07-SC-01)	Sub-package, benefit group
Procedure	Intervention (SHA-07-001)	Service, item, tariff line, product
Service	Intervention component	Sub-service, activity
Protocol	Session or regimen rules	Care pathway, clinical protocol
Drug / item	Product	Item, consumable, SKU

The traversal is what an operator sees as three screens. In your code it is one graph, and the same query with a different member, facility or cover comes back different.

Read three things off that response.

The tree is per member. beneficiary_cr_id is a parameter, not a filter you could apply afterwards. Two members at the same facility get different trees, and caching one member's tree as "the benefit catalogue" is how a patient gets offered something they are not entitled to.

Several funds share one tree. PMF-* and SHA-* codes arrive interleaved, sorted by code rather than grouped by fund. Group them yourself, and label the fund on screen, because a clinician choosing "Inpatient" needs to know whether they are spending the national benefit or the employer fund.

The pages are small by default. You get count: 30 over totalPages: 2 here, so a sync that reads page one only ships two thirds of a tree and looks like it worked.

What a procedure declares

This is the densest object in the step. Every field on it changes behaviour somewhere later, and a payer may declare any of them higher up instead, in which case what arrives here is what it inherited.

The calls that walk it

The handle is the selection_ref from covers/select, not an eligibility reference: v2 has none. Reading the tree also takes no consent proof — the proof is redeemed later, at POST /api/v2/claims/authorize.

Most limits count visits rather than money

Anyone arriving from private insurance has to unlearn this one. A limit here is as likely to be a number of times as a sum of money.

A balance screen that only knows how to render currency will show nothing useful for most benefits. Read which kind you are holding before you format it.

Some employer schemes carry their own fund balances alongside the national ones. Where a cover exposes them, they are read per benefit rather than per procedure.

What you keep

What breaks here

What carries forward

The procedure code and its access point go to 06 · Preauthorize where approval is required, and to 07 · Bill where it is priced.

Back to02 · Verify cover→

Which cover pays: the covers a member holds, who contributes to each, what gets frozen onto the encounter, and when that choice stops being changeable.