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.
Two ways to raise a preauth
You can embed the rail's preauth page, or build your own screens on the API. We recommend the page. It works like the consent page: you load a one-time link in an iframe, and the operator does the work inside it. The page uses the same calls as the API below, so the checks and the states are the same.
| Embedded preauth page | Your own screens | |
|---|---|---|
| Clinical form for the benefit type | The rail renders the payer's published form | You build one per request type |
| Preflight blockers | Shown on the page before submit | You call preflight and show reasons[] |
| Doctors, diagnoses, items, attachments, notes | Edited on the page | One API call each |
| Resubmit, finalise, cancel, start a new preauth | Buttons on the page | Separate API calls |
| Decision | Callback and GET …/preauths/{preauth_ref} | Callback and GET …/preauths/{preauth_ref} |
Embed the preauth page
- 01Read the visit's service linesWhen the operator opens a line, your backend calls GET /api/v2/visits/{visit_ref}/service-lines. Each line that can take a preauth carries next_action with type render_preauth, method GET and a one-time launch endpoint.
- 02Build the frame URLnext_action.endpoint is a path, such as /api/v1/ui/launch?code=…. Put the rail base URL you call the API on in front of it, including any path such as /orchestrator. Add nothing else.
- 03Load it in an iframe within five minutesThe link works once. The operator fills in the clinical details, doctors and diagnosis, charges and attachments, and submits on the page.
- 04Get the decision on your backendThe decision reaches the callback_url you sent on POST /api/v2/visits. Also read GET /api/v2/visits/{visit_ref}/preauths/{preauth_ref}, as for a preauth raised through the API.
List the visit's service lines. Each read mints a new launch link for every line that can take a preauth.
next_action.endpoint per lineCode
With a base URL of https://api-dev.slade360edi.com/orchestrator, the iframe src is
https://api-dev.slade360edi.com/orchestrator/api/v1/ui/launch?code=3q2Xk….
Before you embed the page
- The page uses the same allowed origins as the consent page. If your origin can frame consent in an environment, it can frame preauth there too. If it cannot, ask the rail team to add it.
- Your tenant needs access to the preauth page. This access is separate from the consent page's, so ask the rail team to enable it in each environment.
- Refresh the bearer token before you read the service lines. The launch carries that token, and the page's session ends when the token expires.
What the page does
The page covers one service line. A summary strip shows the line, its cover and the current preauth state. Below it, a stepper takes the operator through these steps:
- Clinical details. The payer's form for the line's benefit type, such as surgical, renal or optical. Answers are saved as a draft for each line, so the operator can leave and come back.
- Doctors and diagnosis. The requesting doctors and the diagnoses on the line.
- Charges. The items to preauthorise, each with a code, name, unit price and quantity.
- Attachments. The documents the payer requires, including documents added before the preauth was raised.
- Clarifications. The notes exchanged with the payer about this preauth.
One action bar holds the main action for the current state, Submit preauth, Submit changes or Finalize, and Cancel. The page runs preflight and lists the blockers before submit. The form opens even when the line is not ready, so the operator can fix what preflight names. When a preauth is decided or closed, the page can start a new one for the same line.
Finalize applies to Slade covers. When the payer has answered, the provider finalises the preauth on the page. A cancel needs a reason, and the page posts the reason to the notes after the cancel succeeds.
A line with no next_action needs no preauth button. Lines on SMART covers never have one,
because SMART raises no preauth.
Or submit through the API
Run the preflight first. It checks the held line with no side effects and names each blocker, such as a missing doctor or diagnosis, an undelivered document, or clinical data that is missing or malformed.
Check a held line is ready. A submit needs the last preflight on the line to have passed.
Then submit. The request is thin, because the rail builds the rest from the visit's record.
Submit one held service line. JSON body, 202 with a reference to watch.
Code
service_line_ref and items are required, and each item needs code, name, unit_price and quantity, all strings. Everything else is optional. Diagnoses are never sent; the ones linked to the line are used. doctors falls back to the visit's practitioners, and every preauth needs at least one doctor. There is no consent token on this call: the rail reads the line's authorisation itself, so an integrator never handles it.
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.
Slade covers: a draft, sent in rounds
A Slade preauth is built as a draft on Slade and sent in rounds.
POST /api/v2/visits/{visit_ref}/preauths/{service_line_ref}/itemsadds one item. On a Slade cover, the first item opens the draft on Slade. The submit then sends the round.- Slade holds one draft for each cover. While one line's draft is open, a second line on the same
cover is refused with
PREAUTH_DRAFT_OPEN_ON_COVER. Submit that draft, or discard it withDELETE …/preauths/{service_line_ref}/draft. - After the payer answers, add items for the next round and submit again.
preauth_roundon the service line counts the rounds sent. - A Slade line can be preauthorised during the visit even when its benefit does not require it.
On an SHA cover, a line that does not need a preauth is refused with
PREAUTH_LINE_NOT_HELD. - When the payer has answered, the provider finalises the preauth. The embedded page has a Finalize button for this.
The states
state is one coarse value whichever payer is deciding, so your state machine never branches on payer. decision qualifies a decided state and closure qualifies a closed one. Both are empty while the preauth is in flight. payer_state is the payer's own wording, relayed.
| Call | What it does | What you keep |
|---|---|---|
submitted | Received and with the payer | not terminal |
needs_more | The payer wants something further, such as a document or a doctor's sign-off | not terminal |
decided | Decision is approved, partial or rejected. Approval brings authorization_code and valid_to | authorization_code, valid_to, items[] |
closed | Closure is expired, withdrawn, cancelled or lapsed. A withdrawn approval is one already given and taken back | terminal, stop billing against it |
Four states, but decided is not the end. 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. It works on a closed visit. GET /api/v2/visits/{visit_ref}/preauths lists every preauth the visit raised.
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.
- Send a
callback_urlwhen you open the visit atPOST /api/v2/visits. Each change in a preauth's state is POSTed there withevent: "preauth.status_changed". A failed delivery is retried, so the same event can arrive more than once. - Read
GET /api/v2/visits/{visit_ref}/preauths/{preauth_ref}as well, at the interval inpoll_after_ms.
Code
preauth_reference is the reference the submit returned. to_state is the payer's state, and
final_approved_amount is present once the payer has decided. Use the callback to know when to
read the preauth, and read the preauth for the decision you act on.
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. GET /api/v2/visits/{visit_ref}/documents lists what the visit still requires.
- 02Note which stage each belongs toPreauthorisation documents and claim documents are separate sets, and the response distinguishes them.
- 03Upload after submittingPOST /api/v2/visits/{visit_ref}/preauth-attachments, multipart, one file per call, up to 10 MiB. Fields: service_line_ref, document_type (a payer code such as DISCHARGE_SUMMARY), and the file in a field named attachment. It answers PREAUTH_NOT_SUBMITTED if the line has no submitted preauth.
- 04Send the correct content typeA PDF sent as something else produces a confusing failure rather than a clear rejection.
Attachments are not part of the submit body. A submit that carries an attachments array belongs to the legacy form-based endpoint, which the rail does not teach.
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. |
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Preauth page | "The preauth frame loads a 404 or our own app" | next_action.endpoint is a path. Put the rail base URL, including any path such as /orchestrator, in front of it. |
| Preauth page | "The preauth link worked yesterday and is refused today" | A launch link opens the page once, within five minutes. Read GET …/service-lines again for a new link each time the page opens. |
| Preauth page | "Consent frames fine but the preauth page is forbidden" | Access to the preauth page is granted separately from consent. Ask the rail team to enable it for your tenant in that environment. |
| Preauth page | "We showed the preauth as submitted when the frame closed" | The page sends no message to your page. Read the preauth, and wait for the decision callback. |
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.

