04 · Visit
Opening a visit touches no payer. It is an encounter and its account, written together in one atomic step, so the clinical record can start even while every payer is down.
Everything below elaborates this sentence.
Why this stop exists
The visit is the container everything else attaches to. It is an encounter first — conditions, observations, CDSS and generated documents hang off it — so it has to be clinically native before it is ever billable.
Opening it is local. The rail writes an Encounter and an Account to its own clinical
store in a single atomic write and calls no payer. A visit with no covered lines is a purely
clinical visit and stays that way until one is added. Everything that touches a payer — the
authorization, the claim — happens on the lines you attach afterwards, and each is its own
answer that never un-opens the visit.
Open the visit
Open an encounter and its account. service_type — OUTPATIENT or INPATIENT — is the only
required field; it becomes the encounter's class and the service type every later
authorization carries.
visit_refIdentity and a service type are the whole of a clinical visit:
unique_patient_idservice_typevisit_refTo open against a cover, send the committed selection_ref from 02 · Verify
cover, the consent_ref the consent ceremony minted (below), and one
or more service_lines, each naming its cover:
Code
selection_ref is required once service_lines is present; consent_ref is required once a
selection is in scope. A clinical visit sends none of them.
The consent it spends is a reference, not a proof
The consent ceremony happens end to end in the consent surface at 03 ·
Consent — the decision, the OTP or biometric, the verification. What
opening a visit receives is the consent_ref that ceremony produced: a redeemable
reference to a verified consent, not the raw proof. Open spends it once, by binding it to the
encounter.
Service lines — the authorization unit
A service line is one intervention plus the cover it draws on. It is the unit a payer authorizes and reserves balance against, and it is payer-first: the rail writes the line as pending, asks the payer, and moves it to the answer the payer gave.
Authorize a cover for a named intervention. The same thing a line at open does, available after the fact — a visit opened clinical becomes billable here.
service_line_refcodecoverthe payer's answerThree outcomes, and only one is an error you resolve by changing the line:
| Call | What it does | What you keep |
|---|---|---|
authorized | The payer reserved balance against the intervention | service_line_ref → add bill lines under it |
refused | The payer declined; its machine code and reason are relayed verbatim | read the verdict, then fix or drop the line |
pending | The payer did not answer; the line is kept durably and is retryable | PAYER_UNREACHABLE (502) → retry the same request |
A refused or unreachable payer never un-opens the visit. The line carries the outcome; the encounter and everything clinical proceed regardless.
Record the practitioner
Who performed a service is stated once on the visit and referenced by every bill line, rather than re-typed per line. The identification is checked against the Health Worker Registry when it is added, so a bad registration number is refused at the desk — not when the payer's claim bounces a week later.
Record a performer. Verified against the registry under its regulator before it is stored.
practitioner_refIt can happen at any time after open — nothing about opening a visit or authorizing a service line waits on a clinician being known.
Record a diagnosis
A diagnosis is a clinical fact first and a claim field second: it exists on visits that
never bill, it is recorded by a clinician rather than the desk, and it changes over a visit.
It is written to the clinical record — a Condition on the encounter — so CDSS, document
generation and the claim builder all read the same one.
Record a diagnosis against the encounter. No cover appears here — a clinical diagnosis needs none, and a payer that requires one enforces that on the claim.
diagnosis_refWhat breaks here
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Visit | "It says consent required" | The visit named a selection but no consent_ref. Run the consent ceremony first and pass the reference it returns. |
| Visit | "Consent not redeemable" | The consent expired, was already spent, or was taken for a different purpose. It is a fresh ceremony, not a retry — the redemption policy decides. |
| Visit | "That cover is not in the selection" | A service line named a cover the committed selection does not carry. A cover outside the selection needs its own selection and its own consent. |
| Bill | "No authorized service line for this charge" | A bill line drew on a service line that is pending or refused. There is no authorization for the charge to draw down until the line is authorized. |
| Bill | "Practitioner not on the visit" | The bill line referenced a practitioner_ref that was never added. Record the practitioner first; it is validated once, there. |
Errors
The rail's own refusals, before any payer is asked, carry a stable error code. Everything
else is the payer's verdict, relayed with its status intact.
| HTTP | error | When |
|---|---|---|
| 404 | PATIENT_NOT_FOUND | The clinical store holds no patient under that identity. |
| 400 | SERVICE_TYPE_INVALID | service_type was not OUTPATIENT or INPATIENT. |
| 400 | CONSENT_REQUIRED | A selection is in scope but no consent_ref was sent. |
| 404 | CONSENT_NOT_FOUND | consent_ref resolves to nothing. |
| 409 | CONSENT_NOT_REDEEMABLE | Expired, consumed, or wrong purpose — the policy's own code is in detail. |
| 409 | SELECTION_UNUSABLE | The selection is unknown, inactive, or belongs to another patient. |
| 409 | COVER_NOT_IN_SELECTION | A line named a cover the selection does not carry. |
| 409 | VISIT_NOT_OPEN | The visit exists but no longer admits changes. |
| 409 | SERVICE_LINE_MISSING | A bill line named no authorized service line. |
| 409 | SERVICE_LINE_NOT_AUTHORIZED | The service line is pending or refused. |
| 409 | PRACTITIONER_NOT_ON_VISIT | The referenced practitioner was never added. |
| 422 | PRACTITIONER_INVALID | The registry did not resolve the identification under its regulator. |
| 502 | PAYER_UNREACHABLE | The payer did not answer; the line stays pending and the call may be retried. |
Next
Next: 05 · Treat — the clinical record on the open encounter, then 07 · Bill to charge under an authorized line.