05 · Treat
A diagnosis costs one click while the clinician is still in the room. Reconstructed weeks later from a rejected claim, it costs somebody a morning, and what you end up with is a guess with a code on it.
Everything below elaborates this sentence.
Why this stop exists
Between opening the encounter and billing for it, somebody is examined, something is found and something is done. Every stop around this one already assumes that record exists. Preauthorisation asks for the diagnosis behind the request. The claim carries one diagnosis per intervention and is assessed on the pair. The patient's next facility needs to know what happened at this one.
Without a stop of its own, all of that gets assembled at submission by whoever is closing the claim. That is the wrong person at the wrong time, working from notes rather than from the encounter.
This is an interchange, and the fork is an unusual one. One branch carries the clinical record onward to the payer, and the other leaves the rail entirely for the shared health record. The same act of recording feeds both, so you only do it once.
What is recorded here
| Call | What it does | What you keep |
|---|---|---|
The diagnosis | What was found, as an ICD-11 code taken from the terminology service. It is never typed by hand and never mapped from a local string at submission time. | diagnosis_id |
The link to the intervention | Which billable intervention this diagnosis justifies. The payer assesses the pair, so a diagnosis with nothing attached fails, and so does an intervention with nothing behind it. | intervention_code |
The encounter itself | The clinical facts as FHIR: observations, notes, impressions and the conditions treated. They are written to the shared health record through the same call. | bundle_id |
What was requested | Orders and prescriptions. They are routed to whoever performs them, frequently not you, and answered back against the request. | order_id, prescription_id |
Where the patient goes next | Referrals and specimens, carrying the record and the authorisation already taken here. | referral_id |
The first two are what stop claims bouncing. The rest is what makes the record worth having, because the same facts, recorded once, serve the claim, the next facility, the patient's own record and, as the last section on this page explains, the documents the claim requires.
Recording clinically is the decision everything else rests on. The rest of this stop follows from having done it.
Take the code from the service, not from a list you keep
Search ICD-11 for a codable diagnosis in the release the payer is currently validating against.
Two properties of the response decide whether the claim survives.
| Call | What it does | What you keep |
|---|---|---|
codable | ICD-11 contains groupings and chapter headings that are not diagnoses. They come back in a search and they are rejected at assessment. Offer only entries flagged codable. | codable: true |
version | The release the payer validates against moves. A code cached from an older release can be retired without your picker noticing. | the version you resolved against |
Record it against the visit
Record a diagnosis on the visit, linked to the intervention it justifies.
Always
Required
icd11_codedescriptionrankintervention_code
rank is primary or secondary. Exactly one primary per visit, any number of secondaries.
Where the clinician knows it
Optional
certaintyonsetrecorded_by
certainty is confirmed, provisional or differential. A provisional diagnosis is a legitimate thing to record and to bill against, not a placeholder to be tidied up later.
Build the workflow around intervention_code. It is not metadata on the diagnosis; it is the
assertion the payer assesses. One diagnosis can justify several interventions, and several
diagnoses can sit behind one, so record the pair each time rather than recording a list of
codes and hoping the assessor infers the pairing.
The record is amended, never rewritten
Withdraw a diagnosis recorded in error, while the visit is still open.
Withdrawal is available until the claim is submitted, and refused after it with
DIAGNOSIS_LOCKED. That is deliberate, because once a claim has been assessed against a
diagnosis, changing the diagnosis underneath it changes what the payer agreed to. Corrections
after submission are raised against the claim.
Contribute the encounter
Send the encounter as a FHIR bundle. It is validated, written to the clinical repository, and acknowledged.
The bundle is a transaction, so it is written whole or not at all. A validation failure
returns issues[], and each entry names the index and the element that failed, so you can fix
the thing it names instead of re-reading the payload.
Encounter
Required
statusclassperiod
One per visit. Its class matches the access_point the visit was opened with, so an outpatient visit does not contribute an inpatient encounter.
Condition
Required
codeclinicalStatus
The same ICD-11 codes recorded above. Send them here too rather than expecting the rail to derive one from the other; the diagnosis call is a payer assertion, this is the clinical record.
Observation
Required
codevalue
Vitals, results and measurements, LOINC-coded. This is what makes the record longitudinal rather than a list of visits.
DocumentReference
Required
typecontent
Clinical notes: the history, the examination and the plan. Coded by note type so another system can find the discharge summary without reading all of them.
Send it as the encounter progresses, not once at the end. Another facility can already see an acknowledged resource, while a bundle held back until discharge is a record that did not exist at the moment somebody needed it.
Read back what this visit has written: the encounter and every resource under it.
Read it back rather than trusting your own copy. What the repository holds is what every other reader sees, and what the documents below are rendered from.
Encounters hang from an episode
A visit is one attendance. An episode of care is the thread that runs through several of them, such as a pregnancy, a course of chemotherapy or the management of a chronic condition, and it is the unit a clinician thinks in.
The episodes this patient has open, and what each one is about. GET /{id} reads one, and GET /{id}/visit-summary returns everything hanging off it.
Open an episode, or attach this visit to one that is already running.
| Call | What it does | What you keep |
|---|---|---|
Attach before you open | Check for an open episode for this condition first. A new episode per visit produces a record that cannot answer "is this working?" about anything. | episode_id |
The episode may not be yours | It can have been opened at another facility. Attaching to it is what makes a shared record longitudinal rather than a pile of visits. | managing_facility |
Closing is a clinical statement | An episode is closed because the condition was resolved or care was transferred, not because the last visit ended. A closed one refuses new attachments. | status |
Episodes are also what make sessions legible to a payer. A course of dialysis authorised as a series at 06 · Preauthorize is the same thing this records clinically: one episode, many encounters.
What was requested, and who performs it
Ordering and prescribing have the same shape. Something is requested here, performed somewhere else, and answered back against the request. Neither one needs an integration with the performer, because both of you are already on the rail.
| Call | What it does | What you keep |
|---|---|---|
Orders | Labs, imaging, procedures. Panels come back expanded into their parameters, and results return against the order rather than into a mailbox you poll. | order_id |
Prescriptions | Routed to the pharmacy the patient chooses. That pharmacy pulls it from its own inbox, so nothing is carried in on paper. | prescription_id |
Both directions | The same calls make you a performer as well as a requester. A facility that only posts orders has built half of it. | the inbox |
The full set: ordering across facilities, returning results against the expanded parameters, routed prescriptions, partial fills and substitution rules.
Where the patient goes next
A referral carries the record rather than a request to start again, and it carries the authorisation the patient already gave you, so they do not travel to the receiving facility just to authenticate a second time for the same episode.
Continues onReferrals, samples and one authenticationHub and spoke without building hub and spoke: sending patients and specimens, accepting inbound referrals, and how one authentication at the source facility stands at the destination.
The documents generate themselves
This is the first thing all of that recording pays back. Every field a discharge summary or a claim form contains was recorded above, so the rail can render those documents from the clinical data instead of asking somebody to write them.
Generate the documents this claim requires, from what has already been recorded.
Where a document cannot be produced, the response names the clinical elements that are missing rather than form fields. The fix is to record the fact while the encounter is still open, instead of typing it into a template at submission.
An HMIS that records clinically is paperless the day it connects, without building a document editor, a template engine or a PDF pipeline.
Continues onGoing paperless on day oneGenerating the required set, rendering HTML for the screen and PDF for a signature, and why a stored PDF should never be your source of truth.
Read it back
Reading is the other half of contributing. A clinician who can see that a patient was treated for the same thing three weeks ago at another facility makes a different decision, and does not repeat an investigation the payer has already paid for.
What breaks here
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Submit | "The claim was rejected for an invalid diagnosis code" | A grouping or chapter heading was sent instead of a codable entity, or a code from a superseded release. Filter the picker on codable and refresh against the current version. |
| Submit | "Every code is valid and it still bounced" | The diagnoses were not linked to interventions. The payer assesses the pair, and an unlinked diagnosis is not assessed at all. |
| Preauth | "The request came back saying the procedure is not indicated" | The diagnosis does not support the intervention under the payer's clinical rules. The detail block names both codes and the rule, and usually the diagnosis is under-specified rather than wrong. |
| Treat | "We record the diagnosis at discharge" | By then the clinician has gone and the coder is working from notes. Every downstream check that could have been answered in the room becomes a rejection instead. |
| Treat | "The bundle was rejected and we do not know which part" | Read issues[], where each entry carries the index and the element. A transaction bundle is not partially written, so nothing landed. |
Errors
| HTTP | error | When |
|---|---|---|
| 422 | DIAGNOSIS_REQUIRED | Something downstream needs a diagnosis and the visit has none. |
| 400 | DIAGNOSIS_CODE_INVALID | Not in the current release, or not a codable entity. |
| 422 | DIAGNOSIS_NOT_LINKED | A diagnosis with no intervention, or an intervention with no diagnosis. |
| 422 | DIAGNOSIS_INTERVENTION_MISMATCH | The pair is refused by the payer's clinical rules. |
| 409 | PRIMARY_DIAGNOSIS_CONFLICT | More than one diagnosis ranked primary. |
| 409 | DIAGNOSIS_LOCKED | Amended after the claim was submitted. |
| 400 | CLINICAL_BUNDLE_INVALID | The FHIR bundle failed validation. |
| 403 | CLINICAL_CONSENT_MISSING | No consent covering clinical sharing. |
Every code recorded at this stop comes from the terminology service. How to fetch one, cache it by version, and find out when the release moves.
Next
Next: 06 · Preauthorize
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.