Cases
Filing an asynchronous consult, the statuses it moves through, and what falls out of a decision.
A case is one asynchronous consult: what was requested, what the patient answered, and where a licensed clinician has taken it. It is the centre of the API. Everything else either feeds a case (patients, consents, files) or falls out of one (messages, prescriptions, orders, events).
Filing one
POST /v1/cases needs cases:write and four things:
patient, apat_…id.requested_medications, one to ten lines, each naming amedication_idfromGET /v1/medications. A line may state aquantity(1 to 999),refills(0 to 12),days_supply(1 to 365) and labeldirectionsof at most 140 characters; each is optional, and a line that states none of them leaves the dose to the prescriber. You may name apharmacy_id, addpharmacy_notes, or setno_substitutions.answers, one to three hundred intake answers. Each carries a stableid, thequestionas the patient saw it, theanswer, and atypeofboolean,number,stringorchoice. Setimportantorcriticalto raise an answer in the clinician's view.consent_ids, the consents this case is filed under. A case filed without a current telehealth and privacy consent answers409 consent_required.
To leave the whole dose to the prescriber, send prescriber_decides: true on the line. The clinician
then sees the medication with no strength, quantity, refills, days supply or directions. Sending it
with quantity, refills, days_supply or directions is a 400 invalid_request with an issue on
that field. Each line a case returns carries prescriber_decides, true exactly when the whole dose
is the prescriber's: the clinician sees no strength on the line and it states none of those four
fields. A line sent without the flag still shows the clinician the medication's listed strength, so
it reads true only for a medication that lists none.
external_id is your own key for the case, unique within the organization. metadata is up to
sixteen string keys of your own state.
Name a question set with question_set: { id, version } and the answers are
checked against it before the case is written: each failing answer is one 400 invalid_request
issue, and the case returns question_set (null when it named none).
Set hold: true to park the case at received instead of queueing it, which is what you want when
you still have files to attach. POST /v1/cases/{id}/release_hold queues it, unless a visit that is
scheduled or started holds the case, which is a 409 conflict.
To have a clinician decide the case live instead, send the same fields as intake on
POST /v1/visits: the case is filed held for that visit and decided at its wrap-up, from
received straight to approved or declined. See Visits.
Where the patient lives
A case is checked against the rule of the patient's state before it is written, so a case no
clinician could decide is refused with what to do instead rather than left in a queue.
GET /v1/states publishes each served state's rule: visit_required (every treatment needs a
live video visit there), visit_required_categories (the treatment categories that do) and
blocked_categories (the ones not offered there). Live rules are whatever GET /v1/states returns
under a live key, and they change as clinical coverage does; test mode's are fixtures (see
Test mode). GET /v1/medications?state=TX and GET /v1/pharmacies?state=TX list
only the rows whose states include that two-letter code.
409 visit_required: the treatment needs a live video visit in the patient's state. Book one withPOST /v1/visitsand send this intake.detailnames the category, the state and that next step, for example:Men's Hormones treatment in TX requires a live video visit, so "Testosterone cypionate" cannot be decided asynchronously. Book a visit with POST /v1/visits and send this intake.409 not_available_in_state: no clinician could approve the case there. The patient has no state on file, no clinician is licensed in it yet, a requested treatment is blocked there, or a line has no category to check against a state that blocks some. Remove the linedetailnames, or correct the patient's address.
Neither is worth retrying unchanged. release_hold asks the same question, so a held case that
needs a visit stays held.
If the patient's state changes while a case is open and the new state needs a visit for it, the
case is held at received and announced with case.visit_required.v1. Book POST /v1/visits with
case set to it; no new intake is needed. A case already held is not announced again, and a case a
booked visit will decide is not announced at all.
The statuses
received -> queued -> in_review -> approved
-> declined
waiting_on_patient <-> in_review
waiting_on_integration <-> in_review
received is where a held case waits. waiting_on_patient and waiting_on_integration mean the
clinician asked a question and named who should answer it. waiting_on_patient also means the case
is held on labs the clinician asked for, with no question written: it returns to
in_review on its own once they are in. cancelled is yours to cause;
withdrawn is an approval later voided. Both approved and declined set decided_at, and a
decline sets decline_reason, which is written for the patient to read.
GET /v1/cases/{id}/status_history returns every status the case has held, oldest first, each with
the status it came from and when it changed. That is an audit you can serve yourself rather than
reconstruct from events.
Cancelling
POST /v1/cases/{id}/cancel withdraws a case that has not been decided, with an optional reason. A
case that has already been decided answers 409 conflict.
A case returns its requested_medications with every key present, null where the line did not
state it. A live line filed before 2026-11-14 returns days_supply, directions, pharmacy_notes
and no_substitutions as null: the clinician saw them as a note, and they are not read back out
of it.
What an approval produces
An approved case produces prescriptions, and a prescription that is dispensable produces an order. Both are read-only over this API, because both are decisions made downstream of you.
GET /v1/cases/{id}/prescriptionsneedscases:read. A line carriesdispensable. When it is false the clinician recorded the line for the record and no pharmacy will fill it, so do not bill or ship against it.days_supplyisnullwhen the clinician's line records none.- Each prescription carries
requested, the case's requested line for the samemedication_id(quantity,refills,days_supply,directions, eachnullwhen the request left it to the prescriber), ornullwhen the case requested no such medication. Two requests for one medication pair with that medication's prescriptions in order.changed_fieldslists the fields the request stated that the prescription sets differently, and is empty otherwise: exactly the fields the comparison reads aschanged: true. A field the prescription states no comparable value for is never a change: nodays_supply, aquantitythat is not a bare whole number (it reads as its leading number, such as3for3 mL vial, or0),refillsthe clinician left blank (it reads0), anddirectionsthe clinician did not write (the line shows the dosage in their place).directionsthat differ only in surrounding spaces are not a change. GET /v1/cases/{id}/prescription_comparisonneedscases:readand sets the whole request beside the prescription, in any status. See Comparing the request and the prescription.GET /v1/cases/{id}/ordersandGET /v1/orders/{id}needorders:read. An order moves throughpreparing,at_pharmacy,shipped,delivered, and carriescarrier,tracking_numberandtracking_urlonce the pharmacy sets them,nulluntil then. No order carries a delivery estimate.blockedalways names a reason ofaddress,prescriber,paymentorattestation, each saying what has to be fixed.failedis terminal.ship_tois the address the pharmacy was sent, null until the order is submitted; a patient's address change after that does not move it (see Patients and consents).
Comparing the request and the prescription
GET /v1/cases/{id}/prescription_comparison answers one line per requested medication, then one per
prescribed medication nobody requested:
{
"object": "prescription_comparison",
"case": "case_7d1e4b2a",
"case_status": "approved",
"has_prescription": true,
"lines": [
{
"medication": {
"requested_medication_id": "med_sildenafil",
"prescribed_medication_id": "med_sildenafil",
"changed": false
},
"prescriber_decides": false,
"outcome": "prescribed",
"quantity": { "requested": 8, "prescribed": 4, "changed": true },
"refills": { "requested": 2, "prescribed": 2, "changed": false },
"days_supply": { "requested": 30, "prescribed": null, "changed": null },
"directions": {
"requested": "Take one tablet as needed.",
"prescribed": "Take one tablet as needed.",
"changed": false
}
}
]
}
outcome | Meaning |
|---|---|
prescribed | The clinician prescribed the medication requested |
substituted | One requested line and one prescribed line were left unpaired, with no retail line, so the second is read as replacing the first |
not_prescribed | No prescription answers this line: the case was approved without one, or it was declined, cancelled or withdrawn |
added | The clinician prescribed a medication the case did not request |
pending | The case is still open, and no clinician has decided it |
sent_to_retail_pharmacy | The clinician sent a prescription to the patient's own pharmacy. Its drug and dose are not published, so every prescribed value is null |
changed is true or false only when both sides state a value. It is null when the line left
the field to the prescriber, when nothing is prescribed yet, or when the prescription does not record
the value: a line that records no days_supply, no refills or no directions reads null. A
quantity compares only when it is a bare whole number on both sides; any other text, such as
3 mL vial, 30 tablets or as directed, reads null, because its leading number need not be a
count of what was requested. A case that is declined, cancelled or withdrawn answers 200 with
has_prescription: false.
A retail prescription counts as a prescription here but never appears in
GET /v1/cases/{id}/prescriptions, and it names no medication, so it is tied to a request only when
that is the one reading: the retail lines answer the requests no other line answered when they match
them one for one and no formulary line is left over. Otherwise nothing is guessed. Each retail line is
a line of its own with every requested value null, a formulary line left over is added, and the
requests read not_prescribed.
Changing where it ships
PATCH /v1/cases/{id}/shipping_address needs patients:write, because it rewrites the patient's
address, and an Idempotency-Key. The body is an address: line1, city, state,
postal_code, and line2, which is cleared when you omit it or send null.
{
"case": "case_7d1e4b2a",
"patient": "pat_3f9a2c10",
"address": {
"line1": "2 Oak St",
"line2": null,
"city": "Dallas",
"state": "TX",
"postal_code": "75201"
},
"updated_at": "2026-11-18T15:04:05.000Z"
}
A 200 is the address this case's order ships to, and patient.updated.v1 announces it. The lock
covers this case's order only. The address belongs to the patient, so another open order of theirs
that is not yet at the pharmacy picks up the change too, and one already at the pharmacy keeps the
old address.
422 shipping_state_change_requires_new_intake: the address is in another state than the patient's, whatever the case's status. A clinician is licensed by state, so file a new intake there.409 shipping_address_locked: the case is declined, cancelled or withdrawn, or an order on it has gone to a pharmacy, including one whose send has started and is not yet confirmed. Some cases carry the address to the clinician with the consult when they go to review, and those lock from then on, before any order exists. An approved case whose order has not been sent can still change, and so can one the pharmacy refused outright on its first send.
Talking on a case
GET /v1/cases/{id}/messages reads the thread and POST writes to it. Reading needs
messages:read, writing needs messages:write. You post as patient or as integration; the
clinician's replies arrive on the same thread and are never writable by you.
Following one
Every transition emits an event. Poll GET /v1/cases/{id}/events for one case, poll GET /v1/events
for all of them, or subscribe a webhook endpoint. Every event carries the resource's status after
the transition, so a delivery that arrives late is still safe to apply. See
Webhooks and Events and realtime.
To drive all of this without a clinician, see Test mode.