Skip to content

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.

OperationWhat it plays
POST /v1/test/cases/{id}/decisionThe clinician approving, declining, or asking a question
POST /v1/test/cases/{id}/clinician_messageThe clinician replying on the case thread
POST /v1/test/cases/{id}/shipThe pharmacy shipping, with optional carrier and tracking
POST /v1/test/cases/{id}/deliverThe parcel arriving
POST /v1/test/cases/{id}/blockThe order stopping, with a reason
POST /v1/test/cases/{id}/failThe order failing for good
POST /v1/test/purchasesA storefront checkout, crediting an affiliate when one is named or its coupon code is sent (Purchases)
POST /v1/test/purchases/{id}/refundMoney going back, in part or whole
POST /v1/test/purchases/{id}/disputeA chargeback opening
POST /v1/test/visits/{id}/startThe visit call beginning
POST /v1/test/visits/{id}/completeThe clinician completing the visit, and deciding the case it was booked with an intake for
POST /v1/test/visits/{id}/no_showThe patient never arriving
POST /v1/test/lab_ordersA lab order, on a case or for the clinic
POST /v1/test/lab_orders/{id}/placeThe patient confirming it, and the lab network taking it
POST /v1/test/lab_orders/{id}/collectThe sample being collected
POST /v1/test/lab_orders/{id}/receiveThe sample reaching the lab
POST /v1/test/lab_orders/{id}/resultThe report, or a correction of it
POST /v1/test/lab_orders/{id}/cancelThe lab network cancelling it, or the clinician waiving it
POST /v1/test/lab_orders/{id}/failThe lab network failing it
POST /v1/test/affiliatesA partner joining the affiliate tree
POST /v1/test/webhooks/triggerAny event type, against a fabricated resource
PATCH /v1/test/autopilotThe timers below
POST /v1/test/resetWiping 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 requesting med_testosterone_cyp or med_estradiol without one is refused with 409 visit_required. Book POST /v1/visits with 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.