Flow
Every path a provisioning request can take.
The three charts below were derived from the branches the system actually runs. The happy path is here, and so is where a refusal, a choice, a wait and a change of mind each end up.
How to read it
- Entry and merge point
- Something the system does
- A branch
- An outcome that settles
- An outcome that refuses
- An outcome that waits or gives money back
The numbers in the boxes are the HTTP status codes the API returns. These are the answers you will handle during integration.
1. From request to decision
Every branch between the patient arriving and the engine running. A disabled system, a repeated request and a patient holding more than one policy all separate here.
The patient arrives at the hospital
The HBYS sends the line items in a single request
Is the provisioning engine on?
- ClosedThe request is refused. The hospital falls back to the phone.
- OpenHas this request id arrived before?
The request is refused. The hospital falls back to the phone.
503
Has this request id arrived before?
- YesDid the earlier attempt produce an answer?
- NoCan the request's demo/live mode be established?
Did the earlier attempt produce an answer?
- YesThe same answer returns. Nothing is computed twice.
- NoAre the line items identical to the first submission?
The same answer returns. Nothing is computed twice.
Are the line items identical to the first submission?
- NoThe items changed. A changed order is a new request; resend under a new request id.
- YesCan the request's demo/live mode be established?
The items changed. A changed order is a new request; resend under a new request id.
422
Can the request's demo/live mode be established?
- NoMode unresolved. Refused on the safe side; retry shortly.
- YesDid the patient name their insurer?
Mode unresolved. Refused on the safe side; retry shortly.
503
No policy there. The others are not asked, because the patient named this one.
404
Did the patient name their insurer?
- YesDoes that insurer hold a valid policy?
- NoEvery active insurer matching the request's mode is asked in parallel; where the installation requires a contract, the list is narrowed to the hospital's contracted payers
Does that insurer hold a valid policy?
- NoNo policy there. The others are not asked, because the patient named this one.
- YesThe policy is settled
This hospital has no contract on file with any active payer. The request is refused; the patient is not reported as uninsured.
503
Every active insurer matching the request's mode is asked in parallel; where the installation requires a contract, the list is narrowed to the hospital's contracted payers
- List left emptyThis hospital has no contract on file with any active payer. The request is refused; the patient is not reported as uninsured.
- How many valid policies matched?
A choice is needed. The candidate policies go back to the hospital.
409
- The patient is asked which policy to use
How many valid policies matched?
- 0No policy found, or the insurer did not answer
- 2+A choice is needed. The candidate policies go back to the hospital.
- 1The policy is settled
No policy found, or the insurer did not answer
404 / 504
The patient is asked which policy to use
- The HBYS resubmits the choice under the same request id
The policy is settled
- Was the policy in force on the encounter date?
The HBYS resubmits the choice under the same request id
- Did the patient name their insurer?
Was the policy in force on the encounter date?
- NoThe policy was not in force on that date
- YesThe policy is bound to a local policyholder record; an externally-held policy is mirrored in on first sight
The policy was not in force on that date
422
The policy is bound to a local policyholder record; an externally-held policy is mirrored in on first sight
- Bad identity / no planPolicy identity incomplete or plan not provisioned. The fault is on the source side, not the hospital payload.
- If complementary, is the scheme's share known?
Policy identity incomplete or plan not provisioned. The fault is on the source side, not the hospital payload.
502
If complementary, is the scheme's share known?
- UNREACHABLEIt could not. The request is refused rather than decided as if the scheme paid nothing.
- The line items enter the engine
It could not. The request is refused rather than decided as if the scheme paid nothing.
503
The line items enter the engine
2. Every line passes 12 gates
The engine evaluates the lines one at a time, always in the same order. Some gates can refuse a line outright: the contract, the scope, the policy date, the coverage, the waiting period, a rule that rejects, and the frequency cap. The price and public-scheme gates neither refuse nor clamp; the first sends the decision to the insurer’s reviewer when the billed price is far above the tariff, the second subtracts the public scheme’s share on a complementary policy so the percentage applies to what is left. The remaining gates only reduce the insurer’s share, and a matching rule can ask for a reviewer instead of rejecting.
One line item enters the engine
- Is the hospital on the contracted list, or does a rule make this an exception?
This step only runs where the installation requires a network. Emergencies and a payment guarantee the payer itself issued can be carved out by rule; the rule that opened the gate is named in the trace.
Is the hospital on the contracted list, or does a rule make this an exception?
- NoNeither a contract nor an exception. The request is refused.
- YesIs the procedure in the policy's scope?
Neither a contract nor an exception. The request is refused.
Is the procedure in the policy's scope?
- NoOut of scope. The patient pays all of it.
- YesIs the policy active on the encounter date?
Out of scope. The patient pays all of it.
Is the policy active on the encounter date?
- NoThe policy is not active on that date
- YesIs there cover defined for this procedure?
The policy is not active on that date
Cover is matched on two axes, procedure specificity and contract tier: the same procedure can be priced at a different rate and a different cap at one hospital
Is there cover defined for this procedure?
- NoNo cover defined. The item is rejected.
- YesIs the billed unit price reasonable against the tariff?
No cover defined. The item is rejected.
Is the billed unit price reasonable against the tariff?
- YesThe price looks like an outlier. The line is neither refused nor clamped; the decision does not auto-finalise and goes to the insurer’s reviewer.
- NoHas the waiting period elapsed?
The price looks like an outlier. The line is neither refused nor clamped; the decision does not auto-finalise and goes to the insurer’s reviewer.
Has the waiting period elapsed?
- NoWaiting period not over. The days remaining go into the answer.
- YesA complementary policy?
Waiting period not over. The days remaining go into the answer.
A complementary policy?
- YesThe scheme's share and the statutory co-payment come out first. The percentage applies to what is left; the co-payment is carried whole by the policy or by the patient.
- NoDoes a rule match?
The scheme's share and the statutory co-payment come out first. The percentage applies to what is left; the co-payment is carried whole by the policy or by the patient.
The first rule that says approve wins and replaces the cover percentage
Does a rule match?
- RejectsA rule rejects this item
- Pre-authThe rule asks for pre-authorisation. The shares it computed are kept; the decision does not finalise and goes to the payer's reviewer.
- Is the per-item cap exceeded?
A rule rejects this item
The rule asks for pre-authorisation. The shares it computed are kept; the decision does not finalise and goes to the payer's reviewer.
Is the per-item cap exceeded?
- YesTrimmed to the cap. The patient pays the difference.
- NoIs the frequency cap reached for this window?
Trimmed to the cap. The patient pays the difference.
Is the frequency cap reached for this window?
- YesThe line is refused. A cap that is full means out of cover, not a discount.
- NoWould this exceed the sub-limit for the window?
The line is refused. A cap that is full means out of cover, not a discount.
Would this exceed the sub-limit for the window?
- YesTrimmed to the sub-limit. The patient pays the difference.
- NoIs there enough annual limit left?
Trimmed to the sub-limit. The patient pays the difference.
Is there enough annual limit left?
- Not enoughOnly what is left is paid. If the limit is gone, the patient pays all of it.
- EnoughLine result: insurer share, patient share and the scheme's share where there is one
Only what is left is paid. If the limit is gone, the patient pays all of it.
Line result: insurer share, patient share and the scheme's share where there is one
The lines are added up. All approved is approved, all rejected is rejected, anything between is partial.
3. What actually spends the money
An approval does not spend money, it holds it. The hold is released by the hospital reporting delivery, by the patient walking away, or by the clock running out.
The decision waits. Nothing is held, no notification is sent.
- The insurer’s staff review it: approve, optionally with reduced line shares, or reject with a reason
Does the decision go to a reviewer? (review is on for the payer, the price is an outlier, or a rule asked for pre-auth)
- YesThe decision waits. Nothing is held, no notification is sent.
- NoIs the insurer share greater than zero?
The insurer’s staff review it: approve, optionally with reduced line shares, or reject with a reason
- approveOn approval the amount is held and the clock starts
- rejectIs the insurer share greater than zero?
Is the insurer share greater than zero?
- NoThere is nothing to hold. The decision closes.
- YesHeld against the held side of the annual limit, 72 hours by default.
There is nothing to hold. The decision closes.
On approval the amount is held and the clock starts
Held against the held side of the annual limit, 72 hours by default.
- Care was delivered. The hospital reports it and the held amount becomes spent.
- The patient walked away. The hospital cancels, the hold is released and the limit reopens.
- Nobody closed it. When the clock runs out the hold is released by itself.
An approval does not spend. The held amount sits inside the insurer's limit without counting as spent.
Exception: if the insurer cancels while it waits, the row closes as voided; approval then refuses.
Care was delivered. The hospital reports it and the held amount becomes spent.
- The decision is sent to the insurer as a signed notification
The patient walked away. The hospital cancels, the hold is released and the limit reopens.
- The decision is sent to the insurer as a signed notification
Nobody closed it. When the clock runs out the hold is released by itself.
The decision is sent to the insurer as a signed notification
Did the notification arrive?
- NoRetried a few times at widening intervals
- YesMarked as delivered
Retried a few times at widening intervals
- If it never arrives it lands in the dead-letter list where an operator sees it
Marked as delivered
If it never arrives it lands in the dead-letter list where an operator sees it
Want to see it with your own rules?
In a sandbox account you can define your own cover and limits and run the same flow against your own data.