Getting started

The Cuvo Integrations API is one REST surface at https://api.cuvo.co. Every request carries a secret key as a bearer token, names the organization it acts for, and answers JSON. Start in test mode: a test key reaches a sandbox that holds only the data you invented for it, so you can drive a case from intake to delivery before a real patient exists.

Four things to do first

1. Create an account at developers.cuvo.co and verify your email.
2. Create an integration. It is the thing that holds credentials, grants, webhook endpoints and billing.
3. Mint a test key. It is shown once, starts with cuvo_sk_test_, and carries the scopes you tick.
4. Ask a clinic for access. You send its org_… id and the scopes you need; the clinic approves the grant. In test mode you are given a sandbox organization straight away.

Live mode needs two more things: an accepted business associate agreement, and a cuvo_sk_live_ key. See Authentication.

Your first call

GET /v1/organization tells you which organization the credential acts for, in which mode, with which scopes. It needs organization:read.

curl https://api.cuvo.co/v1/organization \
  -H "Authorization: Bearer cuvo_sk_test_…"

{
  "id": "org_c8k2q1w9",
  "name": "Northgate Health",
  "slug": "northgate",
  "kind": "DIRECT",
  "status": "active",
  "mode": "test",
  "scopes": ["organization:read", "patients:write", "cases:write", "events:read"]
}

The scopes list is what this credential can actually do here: your key's scopes intersected with what the organization granted. If something is missing from it, the call that needs it answers 403.

The loop

The API is one shape repeated. You create a patient, record the consents they accepted, file a case, and then follow what the clinician and the pharmacy do with it through events.

1. POST /v1/patients with a name, date of birth, sex at birth, email, an E.164 phone number and a US address. You get back a pat_… id.
2. POST /v1/patients/{id}/consents once for telehealth and once for privacy, each with the version of the document the patient saw. A case filed without both current consents is refused with consent_required.
3. POST /v1/cases with the patient, at least one requested medication from GET /v1/medications, the intake answers, and the consent ids. The case arrives at queued, or at received if you set hold so you can attach files first.
4. Read GET /v1/cases/{id}/events, or subscribe a webhook endpoint, and watch the case move through in_review to approved or declined. An approval produces prescriptions, and a prescription produces an order.

curl https://api.cuvo.co/v1/cases \
  -H "Authorization: Bearer cuvo_sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: case-2026-09-08-0001" \
  -d '{
    "patient": "pat_9f2b7c4a",
    "consent_ids": ["cons_1a2b3c4d", "cons_5e6f7a8b"],
    "requested_medications": [
      {
        "medication_id": "semaglutide-0-25mg",
        "quantity": 4,
        "refills": 0,
        "days_supply": 28,
        "directions": "Inject 0.25 mg subcutaneously once weekly."
      }
    ],
    "answers": [
      { "id": "goal", "question": "What are you hoping to achieve?", "answer": "Weight loss", "type": "string" }
    ]
  }'

Moving the sandbox

Nothing decides a sandbox case on its own unless you ask it to. POST /v1/test/cases/{id}/decision plays the clinician, /ship and /deliver play the pharmacy, and PATCH /v1/test/autopilot sets timers so a demo runs untouched. See Test mode.

Where to go next

Authentication for credentials, Scopes and organizations for what a grant decides, Cases for the resource everything else hangs off, Visits when the consult is a live video call instead, and Webhooks for the delivery loop. The full operation list is in the API reference.