Skip to main content
Two different things are called “medications”, and this page keeps them apart.
  • A reported medicine (a medication statement) says “the patient, or an outside system, reports taking this”. Reading the list is immediate. Writing is different: a medicine you send is held for a clinician to review, and only a clinician’s decision puts it on the chart. Read Reviewing outside submissions first if you have not already, because everything about sending builds on it.
  • A prescription is an order the clinic wrote or sent electronically. It drives dispensing and billing. You can only read prescriptions. No request can create, change or cancel one, and none ever will.
The patient must be one your key is allowed to see. A patient the clinic has restricted, or a record that does not exist, returns 404 with code: "not_found". The two are never told apart. See Errors.

​
Reported medicines

​
What one looks like

A report you sent that is still waiting has "id": null: it has no place on the chart yet. Use submission_id to follow it. A reported medicine is not a prescription: it says what the patient reports, and records no order, supply or dose instruction from the clinic.

​
Codes

medication.code.system is rxnorm or local. Send both parts or neither, or just the medicine’s name.
  • rxnorm is checked against a verified list of medicines. A code that is not on it is refused with invalid_request, and the detail says the code is not recognised. A real RxNorm code that is not on our list is refused too: send the medicine as text, or with a local code. Never send an RxNorm code from memory.
  • local is your own code, up to 64 characters.
A medicine with no recognised code is still accepted and reviewed. It is simply handled differently by the clinic’s pharmacy checks (see below).

​
List reported medicines

  • confirmed is the patient’s reported list as it stands on the chart.
  • pending is the reports your own key or organization sent that are waiting for a decision, plus those declined, each with its review_status. You never see another party’s submissions.
  • all is both together.
An item with review_status other than confirmed is not on the chart. Do not show it to a person as part of their record. An empty list does not mean the patient takes no medicines. It means nothing has been confirmed.

​
Send a reported medicine

A field not listed here is refused with invalid_request, naming it. The same medicine can be reported more than once: there is no duplicate refusal. Idempotency-Key is required on POST (optional on PATCH). See Retries and duplicates.

​
The answer is 202, not 201

The body is the submission, showing "status": "pending". A 202 is a receipt. It is not a medicine on the chart.

​
After you send one

  • pending: waiting for a clinician.
  • confirmed: a clinician accepted it. The report is on the chart, recorded under the clinician’s name, with source: "api".
  • rejected: declined, with the reason. Do not resend it unchanged.
  • withdrawn: you took it back while it was pending.
Only the key or organization that sent a submission can read it. Anyone else gets 404.

​
Ask for a change

Send only the fields that change: any of status, dosage, effective_start, effective_end, reason, note. The medicine itself is never changeable. The answer is 202 Accepted and the change waits for review. Setting status to entered_in_error asks the clinic to mark the report as never having been true; it must be sent alone, and once a report is marked so it cannot be changed again. A report already marked entered_in_error cannot be changed.

​
How the clinic’s pharmacy uses a reported medicine

A confirmed reported medicine is used in the pharmacy’s drug interaction checks for that patient, while it is active:
  • With a recognised rxnorm code, it is checked for interactions against what is being dispensed.
  • Without one (free text, a local code), it is not matched by its name. The pharmacist is shown it as not checked, in the patient’s own words, so it is never invisible and never mistaken for cleared.
  • completed, stopped, on_hold, not_taken and entered_in_error medicines, and ones whose end date has passed, are not used.
So a code that is recognised makes the report more useful, and a wrong one is refused rather than guessed at. A clinic can also choose to accept new reported medicines without review. Then the answer to your send already shows review_status: "confirmed" and accepted_automatically: true, and the reported medicine reads accepted_by: "automatic" and verification_status: "unconfirmed" until a clinician reviews it. reviewed_at and reviewed_by_staff_id are null until then. A change is always reviewed. See Automatic acceptance.

​
Prescriptions

A prescription is read-only, and minimal on purpose. It carries the drug, the dose, how often, its status, and when it was written, and nothing else.
Nothing about payment, who dispensed it, notes, instructions, the visit it came from, ward or schedule detail, or a patient’s restricted records is ever returned. A prescription the clinic has marked sensitive is not returned at all. Electronically sent prescriptions are included. A prescription sent through the clinic’s e-prescribing connection appears in the same list with source: "eprescribe", and one that is also a ClinikEHR prescription appears once. The vendor’s own detail is never returned. The e-prescribing service describes a prescription’s progress in its own words, so we translate it: cancelled or voided becomes cancelled, filled or picked up becomes dispensed, sent or pending becomes pending, and anything we do not recognise becomes unknown. Treat unknown as “we cannot tell”.
A request to create or change a prescription is not a route: it returns 404 or 405. A prescription written by the clinic stays under the clinic’s control.

​
FHIR

Send Accept: application/fhir+json to read a reported medicine as a MedicationStatement, or a prescription as a MedicationRequest (always intent: "order"). A prescription’s name is carried as text only, with no code, and its source rides in an extension so an e-prescribed one can be told apart. FHIR is not accepted as input: send and change reported medicines with the JSON routes above, and prescriptions are not writable. A FHIR body is refused with an OperationOutcome. See FHIR R4.

​
The Patients routes

The patient’s older current_medications list is no longer writable through the Patients routes: it is refused, and reported medicines go through this page instead. It stays visible as the clinic’s legacy list, and is not used by the pharmacy’s interaction checks.

​
A worked example

  1. Your intake system reads “metformin 500 mg twice daily” on a form. It sends POST …/medication-statements with the medicine, the dosage and an Idempotency-Key. The answer is 202, with a Location header.
  2. GET …/medication-statements?patient_id=… does not show it. Nothing is on the chart.
  3. A clinician opens Outside submissions at the clinic, reads it and selects Accept. You read the submission again and it is confirmed.
  4. GET …/medication-statements?patient_id=… now returns it with source: "api" and your origin_assistant_name. The clinic’s Medications reported list shows a quiet line, From and your name, beside it. If it has a recognised code, the pharmacy now checks it while it is active.
  5. GET …/prescriptions?patient_id=… is unchanged: reporting a medicine never creates a prescription.
A test key reaches only your workspace’s sandbox, which holds invented patients with invented reported medicines and prescriptions, so you can try the requests above without touching a real chart.