Test mode
The sandbox, the simulated clinician and pharmacy, and how to drive a whole consult without one.
A cuvo_sk_test_ key reaches a sandbox. It holds only the data you invented for it, it is scoped to
your integration, and every row is deleted 30 days after it is written. Do not send real patient
information to test mode.
Test mode is not a mock. The same routes, the same validation, the same problem bodies, the same events, the same signed webhook deliveries. What differs is that behind the seam there is no chart and no pharmacy, so this API gives you the controls to play both.
The sandbox controls
Everything under /v1/test requires the test:manage scope and is refused outright to a live
credential with 403 forbidden. There is no way to reach these from production, which is what keeps
a simulated approval out of a real chart.
| Operation | What it plays |
|---|---|
POST /v1/test/cases/{id}/decision | The clinician approving, declining, or asking a question |
POST /v1/test/cases/{id}/clinician_message | The clinician replying on the case thread |
POST /v1/test/cases/{id}/ship | The pharmacy shipping, with optional carrier and tracking |
POST /v1/test/cases/{id}/deliver | The parcel arriving |
POST /v1/test/cases/{id}/block | The order stopping, with a reason |
POST /v1/test/cases/{id}/fail | The order failing for good |
POST /v1/test/purchases | A storefront checkout, crediting an affiliate when one is named or its coupon code is sent (Purchases) |
POST /v1/test/purchases/{id}/refund | Money going back, in part or whole |
POST /v1/test/purchases/{id}/dispute | A chargeback opening |
POST /v1/test/visits/{id}/start | The visit call beginning |
POST /v1/test/visits/{id}/complete | The clinician completing the visit, and deciding the case it was booked with an intake for |
POST /v1/test/visits/{id}/no_show | The patient never arriving |
POST /v1/test/lab_orders | A lab order, on a case or for the clinic |
POST /v1/test/lab_orders/{id}/place | The patient confirming it, and the lab network taking it |
POST /v1/test/lab_orders/{id}/collect | The sample being collected |
POST /v1/test/lab_orders/{id}/receive | The sample reaching the lab |
POST /v1/test/lab_orders/{id}/result | The report, or a correction of it |
POST /v1/test/lab_orders/{id}/cancel | The lab network cancelling it, or the clinician waiving it |
POST /v1/test/lab_orders/{id}/fail | The lab network failing it |
POST /v1/test/affiliates | A partner joining the affiliate tree |
POST /v1/test/webhooks/trigger | Any event type, against a fabricated resource |
PATCH /v1/test/autopilot | The timers below |
POST /v1/test/reset | Wiping the sandbox |
State rules are fixtures
POST /v1/cases and release_hold check the patient's state in test mode exactly as live does
(Cases), against fixed rules that GET /v1/states publishes under a test key:
- Every one of the fifty states is served, and nothing is blocked in any of them.
- Men's and women's hormone therapy (
mens-hormones,womens-hormones) need a live video visit in every state, so a case requestingmed_testosterone_cypormed_estradiolwithout one is refused with409 visit_required. BookPOST /v1/visitswith the intake instead. - A patient whose address names any other state code is refused with
409 not_available_in_state.
These are fixtures, chosen so both refusals can be exercised. Live rules are whatever
GET /v1/states returns under a live key; do not hard-code the sandbox's.
Deciding a case
An approval carries the plan the clinician settled on, which does not have to match what was
requested. A line with dispensable: false is recorded for the record and will never be filled.
Each prescription it writes carries requested and changed_fields exactly as a live one does.
An approval's note is accepted and ignored: nothing stores it or returns it. A sandbox
prescription written before the sandbox began recording requested reads requested: null and an
empty changed_fields, and one written before 2026-11-20 records no pairing, so the comparison reads
it as answering no request; approve a new case to compare one. GET /v1/cases/{id}/prescription_comparison and
PATCH /v1/cases/{id}/shipping_address answer as they do live; an order locks the address from the
moment the simulated pharmacy takes it. Test mode has no retail pharmacy, so it never answers the
sent_to_retail_pharmacy outcome.
curl https://api.cuvo.co/v1/test/cases/case_7d1e4b2a/decision \
-H "Authorization: Bearer cuvo_sk_test_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: decide-case-ada-2026-09-08" \
-d '{
"decision": "approve",
"plan": [
{
"medication_id": "semaglutide-0-25mg",
"quantity": 4,
"refills": 0,
"days_supply": 28,
"directions": "Inject 0.25 mg subcutaneously once weekly."
}
]
}'
A decline takes a reason, which is written to the case and is safe to show the patient. A
needs_info decision takes a target of patient or integration and the question being asked,
and moves the case to waiting_on_patient or waiting_on_integration.
Labs the clinician asked for on the case hold it: an approval or a question is refused with 409 conflict until every one is resulted or waived, and a decline is not. Waived means cancelled while
no lab has the order, or cancelled a second time after the lab network cancelled it. See
Labs.
Autopilot
Autopilot is off by default. Turn it on and the sandbox approves a case on its own after
approve_after_s seconds, then ships and delivers its order after ship_after_s each, and places
a lab order, then reports it normal, waiting lab_result_after_s before each of the two steps
(so 60 means a report about two minutes later). All three are seconds, 0 to
3600, and null turns that timer off. A background tick runs every minute, so a timer fires on the
next tick after it comes due.
Autopilot approves a queued case, and a case back in review from its labs once every lab order on it is settled, after the same wait counted from its return. A case waiting on its labs is never approved around them, and a case in review with no labs is left for you to decide. It prescribes what each line requested; where a line left a field to the prescriber it fills a placeholder, quantity 1, no refills, a 30 day supply and the directions "Sandbox prescription. Use as directed.", so decide the case yourself when you need other values.
A ship that sends no tracking_number reports plainly fake tracking instead of null: carrier
Sandbox Carrier (unless you named one), a SANDBOX- tracking number and an example.com URL.
curl -X PATCH https://api.cuvo.co/v1/test/autopilot \
-H "Authorization: Bearer cuvo_sk_test_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: autopilot-demo-2026-09-08" \
-d '{"approve_after_s": 30, "ship_after_s": 60, "lab_result_after_s": 60}'
Use it for a demo that runs untouched. Turn it off when you are testing a branch that depends on a case sitting still. Nothing advances a live case on a timer.
Proving a receiver
POST /v1/test/webhooks/trigger emits a real event of a type you choose and schedules real,
signed deliveries for it, so you can prove your receiver before a case exists. Name an endpoint
to send to one endpoint only.
Starting over
POST /v1/test/reset removes this integration's sandbox rows and tells you how many went.
{ "reset": true, "resources_deleted": 47 }
It does not touch your integration, your credentials or your webhook endpoints.
What test mode cannot tell you
DELETE /v1/files exists in test mode and has no live counterpart, so a live delete answers 501 live_not_available. It is the one operation left that does: a document filed against a chart is
part of a clinical record, and removing one is a decision the clinic makes in its own console. The
honest answer rather than a permission error, and the reference lists every
operation with the modes it serves.
A sandbox lab report carries no PDF: pdf_url is null, where a live one is a link that expires in
minutes. Code that follows the link should treat null as "no document", which live mode can answer
too. See Labs.
A sandbox export is worth calling out the other way. It assembles a real bundle out of the
fixtures you made, at the same /v1/exports/{id}/download link live mode hands out, so the code
that collects it is the code you ship. The one difference is that a sandbox document carries no
link to its bytes: the sandbox accepts uploads and serves none back.