06 · Preauthorize
Approval is per item and can be partial. Bill against what was approved, never against what you asked for.
Everything below elaborates this sentence.
Why this stop exists
Some items may not be done until someone has agreed to pay for them. Two things put a line here: an item flagged as requiring preauthorisation at the benefit level, or an item flagged conditional whose condition has now been met.
Either way the affected lines are held: they sit visibly on the bill while everything else proceeds normally. Approval releases them without touching the rest of the invoice.
This is an interchange. The rail forks here between carrying on with the billing and waiting for a decision that is being made somewhere else.
One envelope, one clinical block
Every preauthorisation carries the same outer envelope: the visit, the requesting doctor, the primary diagnosis, the billed items. That part never changes.
What changes is the clinical block, and the benefit type decides which one applies. A surgical request does not have to prove the same things as a renal, oncology, radiology or optical one.
Envelope (always)
Required
visit_idrequest_typenarrativeservice_startitems[]diagnosisdoctor
request_type is planned or emergency. narrative has an enforced minimum length, because a human reads it.
Surgical
Required
procedureadmission_typesurgeon_notes
Optional
pre_op_reportssecond_opinion
Surgery date does not default. A major procedure may require several sign-offs before a decision is possible.
Renal
Required
modalitysessions_per_weekdry_weight
Optional
latest_creatinine
Optical
Required
visit_datelens_typeprescription
Optional
frame_detailsprevious_specslast_replacement
The division of labour is deliberate. Your system already knows what clinical data belongs to each benefit type, and populates it. The rail then confirms, before it accepts anything, that everything the benefit type requires on the current payer is present and well formed. Where something is missing it rejects the request and names the missing field, rather than passing a half-formed request downstream.
Submit
Submit a preauthorisation. The rail validates it against the requirement map for this benefit type and payer.
Submission accepts an idempotency_key. A retry after a network failure then returns the
original reference rather than creating a duplicate. Use it, because duplicates here are
expensive to unpick.
The states
There is one status enum whichever payer is deciding, so your state machine never has to branch on payer.
| Call | What it does | What you keep |
|---|---|---|
submitted | Received, routing in progress | not terminal |
under_review | A reviewer or rule is assessing it | not terminal |
awaiting_doctor_review | Routed for clinical sign-off | doctors_signed_off / doctors_required |
awaiting_manual_approval | A payer officer must approve by hand | not terminal |
approved | Full approval | authorization_code |
partially_approved | Some items approved, some not | per-item amounts |
rejected | No items approved | terminal |
returned | Sent back for correction | resubmit under the SAME reference |
expired | The decision window elapsed | terminal |
withdrawn | An approval already given is taken back. It is rare and terminal, and most state machines have no branch for it. | terminal, stop billing against it |
cancelled | Withdrawn by the requester before a decision | terminal |
lapsed | Approved, but the window to start the work passed unused | terminal, request again |
Twelve states, and the three at the bottom are the ones integrations miss. An approval can be withdrawn after it was given, so "approved" is not a fact you can cache and stop watching. Keep listening on the reference until the work is billed.
The decision
The current state, and the decision once there is one. The body is identical to the callback's.
Bill checks valid_from and valid_to again when the line is added, so the check does not
only happen here. Billing after the window closes needs a fresh preauthorisation rather than
a reuse of this decision.
Seven request types, and they behave differently
A preauthorisation is not one shape. The type decides the required fields, the validation, and in some cases whether a doctor has to sign it, so read the type from the procedure rather than defaulting to a generic request.
| Call | What it does | What you keep |
|---|---|---|
OUTPATIENT · INPATIENT | The general paths. Neither demands a type-specific clinical block, though inpatient carries injury and admission detail where relevant. | the type |
SURGICAL | Its own clinical block, an anaesthesia type, and, where enabled, a doctor's authorisation before it can proceed. It needs a credentialed surgeon, and where an anaesthetist is required, that is a second named practitioner. | surgery date |
RENAL | The strictest of the set: sessions required and an expected session date are both mandatory, because dialysis is authorised as a course rather than an event. | sessions_required, session date |
ONCOLOGY | Sessions and expected date, plus comorbidity and metastases detail. Live for named facilities rather than everywhere. | sessions_required |
RADIOLOGY | Clinical indications and, where sedation is involved, an anaesthesia type. | clinical indications |
OPTICAL | A prescription block per eye (sphere, cylinder, axis, add) plus frame detail. Age limits apply to some optical benefits. | the prescription |
Sessions are the pattern worth reading. Renal and oncology authorise a course of treatment
rather than a single act: you say how many sessions and when they start, and the approval covers the
series. It is the same idea as isMultisession on the procedure, so do not raise a fresh request
per session.
Required fields differ per request type
Each clinical path has its own required set, and the differences are exactly where requests get rejected. Four of them are worth stating plainly, because earlier material had them wrong:
| Call | What it does | What you keep |
|---|---|---|
Surgical | Seven required fields, not six. The surgery date is required, though earlier material described it as optional. | surgery_date |
Renal | Five required fields, not four. The start date is required. | start_date |
Oncology | Five required fields, not four. There is no cancer-staging field on this path, whatever earlier material implied. | — |
Optical | All four description fields can be filled. It is the lens prescription that cannot. | — |
Extra items are dropped quietly rather than refused. If you send items the request type does not accept, the preauthorisation is created without them and nothing tells you. Compare what you sent with what comes back, item by item, rather than trusting a 201.
Decisions arrive; they are not returned
Preauthorisation is asynchronous. There is no synchronous approval.
- Register a callback once for
preauth.decision. It is signed, retried with backoff, and safe to receive twice. - Poll
GETat the interval inpoll_after_ms. It returns the same body as the callback.
Build both. The callback is the fast path; polling is the guarantee.
The doctor workflow
Where an intervention needs clinical sign-off, the request has to reach a specific practitioner. This is the most under-documented part of the step relative to how often it goes wrong.
| Call | What it does | What you keep |
|---|---|---|
Channels differ per facility | A request can go to the doctor's app, by two-way SMS, or by email, and not every facility is enabled for all three. A request sent on a channel the facility is not enabled for never arrives at all. | the enabled channels |
Resend is required behaviour | If the first request fails, or the doctor never saw it, you must be able to resend to any doctor on the preauthorisation. | — |
Remove is required too | After a rejection, the doctor can be removed and another attached. | — |
Some interventions need several doctors | More than one signature triggers peer review. Read the requirement from the intervention rather than assuming one doctor is enough. | how many are required |
A peer review decision is recorded, displayed, and final once made. Build the display, because there is no path that reverses one.
Documents, and when each is checked
The required list is published per intervention, and the check happens at different points: some documents at preauthorisation, some at the claim. Inpatient submissions need a discharge summary and a final bill, while maternity needs only the discharge summary. Collecting the right set at the wrong moment still fails.
- 01Read the list from the interventionNot from a general list. Two interventions in the same category can require different documents.
- 02Note which stage each belongs toPreauthorisation documents and claim documents are separate sets, and the response distinguishes them.
- 03Make uploads idempotentA retried upload must not create a second attachment.
- 04Send the correct content typeA PDF sent as something else produces a confusing failure rather than a clear rejection.
Every line carries its scheme code
A preauthorisation item, like a claim line, is billed against a fund, and the scheme code on the line is what routes it there. It is not an optional override. Lines on one visit can legitimately carry different scheme codes, because a member's covers differ by benefit.
Send it on every item. A line without one, or with the wrong one, is routed to the wrong fund and comes back as an assessment problem rather than a routing problem.
What breaks here
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Preauth | "We sent three items and only one came back" | Some payers accept one item per request. Send one request per item unless you have confirmed otherwise, because the quiet drop is the worst failure mode on this stop. |
| Preauth | "It was rejected for a missing field we did send" | Arrays travelling as encoded text in a form field can arrive empty rather than erroring. Verify the payload shape as well as its contents. |
| Bill | "Approved, but billing still refuses the line" | The approval window closed. valid_to is checked at the moment the line is added. |
| Reconcile | "We billed the approved amount and were still short-paid" | The header total was used instead of the per-item approved amounts. Partial approval is per line. |
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Bill | "We billed against an approval and it was refused" | The approval was withdrawn after being given. Approved is not terminal, so keep watching the reference until the work is billed. |
| Preauth | "The request was rejected and the payload looks complete" | A per-type required field is missing, such as the surgery date on a surgical request or the start date on a renal one, or regulation_body was sent as regulator. |
| Preauth | "Half the items are not on the approval and we were not told" | Extra items are dropped quietly rather than refused. Reconcile what you sent against what came back, item by item. |
| Visit | "The approval expired before the patient came in" | An elective approval has a window to be acted on. Store the expiry with the approval and surface it. |
Next
Next: 07 · Bill
A complete brief for this step — the calls to make, what to persist, and every failure path to handle. Nothing on this page is assumed.