Quickstart

1. Get a test key

Open your developer dashboard (you'll be asked to create an account or sign in) and click Create test key. Test keys are issued instantly and look like ak_test_….

2. Submit a request

Pass the clinical narrative as query plus the patient's contact info. The clinical text should be a complete clinical letter (chief complaint, HPI, ROS, PMH, allergies, assessment, plan). The AI completeness gate will tell you what's missing if it's not ready.

curl -X POST https://api.appendix.com/api/v1/prescribing/query \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "34F, no significant PMH, presents with 3 days of dysuria and urinary frequency, no fever or flank pain. Requests treatment for an uncomplicated UTI. No drug allergies. Not pregnant. ...",
    "patient_email": "patient@example.com",
    "patient_phone": "+14155550123",
    "patient_state": "PA",
    "patient_zip": "19103"
  }'

A complete request responds with:

{
  "encounter_id": "b1a2...",
  "environment": "test",
  "sandbox": true,
  "final_decision_ready": true,
  "consent_url": "https://appendix.com/consent/b1a2...?token=...&sandbox=1",
  "pricing": { "complete_review_cents": 0, "incomplete_review_cents": 0, "note": "sandbox — no charge" },
  "simulated_decision": {
    "status": "completed",
    "clinical_decision": "rx_as_requested",
    "message_to_patient": "[SANDBOX] ...",
    "prescriptions": [ { "medication": "[SANDBOX] Example Medication 500mg", "...": "..." } ]
  }
}

3. Send the patient to the consent URL

Open consent_url in the patient's browser (redirect, link, or embedded webview). They review, attest, consent, and verify identity. In sandbox the flow is fully simulated — no real sign-in, no charge, no physician.

4. Receive the outcome

Track the request from your side via the outcome webhook (encounter.completed / encounter.canceled / encounter.message) or by polling GET /api/v1/prescribing/encounters?external_id=… with your API key. external_id is your own opaque correlation ID (an order ID, a row key — never anything personal) that you pass on the /prescribing/query call; it is echoed back verbatim in both surfaces so you can match outcomes to your records without storing our encounter IDs.

Both surfaces carry the privacy-safe projection only — status, prescription count, and a message doorbell — never clinical content, regardless of your data-visibility mode. They tell you when something happened; how the patient hears from the physician, and what your app can read beyond the projection, depend on which features are enabled for your account — see the next two sections.

How the patient hears from the physician

Appendix communicates with the patient directly — how depends on which consent flow your account uses.

Standard flow (consent modal)

If the physician has a question or a final message, the patient gets an email with a secure chat link. Your app gets an encounter.message doorbell plus a credential-free chat_url to surface in your UI — it opens the same chat, but the patient signs in themselves; the link grants no access on its own.

Developer-consented patients (enterprise)

Patients your organization creates via POST /prescribing/patients have no Appendix sign-in and are never emailed, and no chat_url appears for these encounters. Your app is the patient's channel: read the physician's messages through the details endpoint and relay the patient's replies with POST /prescribing/encounters/{id}/messages (both require full visibility — see Developer-Consented Patients).

In both flows, once the physician approves a prescription the patient receives a text message with a link to choose their pharmacy, and the prescription is transmitted to the pharmacy they choose.

What your app can read

Outcome-only visibility (default)

Your app learns status, prescription count, and that a physician message is waiting — nothing more. The details endpoint is not available and your API key cannot read the patient's chat or clinical record; the care relationship is between the patient and Appendix.

Full visibility

Apps on full visibility read the interaction itself — clinical letter, physician conversation, clinical documentation, prescription details — through a separate endpoint, GET /prescribing/encounters/{id}/details, once the patient has consented to data sharing. The webhook and polling list stay thin either way and just tell you when to fetch. How full visibility is enabled, disclosed to the patient, and gated is covered under Webhooks & Polling.

Required fields

• query — the clinical letter
• patient_email
• patient_phone (E.164, e.g. +14155550123)
• patient_state (2-letter)
• patient_zip (5-digit)

Optional: patient_first_name, patient_last_name, patient_dob, patient_sex. These prefill the consent modal; whatever you omit, the patient enters there (all four are required before submission, and the identity check confirms the name + DOB against their ID).

Optional: images — up to 3 per call, each { url } (https, fetched server-side) or { base64 } plus an optional name; JPEG, PNG, HEIC, or GIF, 10 MB max. Photos of a rash, a wound, or a test result ride with the letter and the physician sees them alongside it. Images persist on the encounter and carry forward across turns (up to 10 per encounter) — don't re-send them on a resubmit. The response echoes the attached set as images[] (id, fileName, mimeType — a receipt, no URL) so your app can confirm the upload to the patient immediately.

Enterprise developers whose organization obtains patient consent itself can instead pass patient_id from POST /prescribing/patients and skip the consent step — see Developer-Consented Patients (Enterprise).