Developer-Consented Patients: End-to-End Example (Enterprise Only)
Four calls, start to finish: create a patient your organization has already consented, submit a clinical letter, read the physician's question, and relay your patient's answer back.
What this example assumes
Two capabilities that Appendix enables per account, both requiring an enterprise agreement. Neither is a setting you switch on yourself.
- Developer-consented patients. Your organization obtains and documents patient consent itself, so you create patients directly and no Appendix consent page is shown. Without this, step 1 answers
403 external_consent_not_enabledand you would submit withpatient_*intake fields and hand your user the returnedconsent_urlinstead. Read more. - Full data visibility. Your app can read the whole interaction back, including the physician conversation, and relay the patient's replies. Without this, step 3 answers
403 data_visibility_not_enabledand step 4 is unavailable — you would poll outcome status instead. Read more.
The example uses a production key (ak_live_…). Swap in ak_test_… to run the same four calls against the sandbox with made-up data — and do that until your agreement is signed and production access is approved. Never submit real personal information before then.
1. Create the patient
/api/v1/prescribing/patientsYour organization has already obtained and documented this person's consent to care from Appendix. consent_attested asserts that, and consent_reference is your own record locator for it — opaque to Appendix, so never put clinical information in it.
patient_ref is your own identifier for this person — a UUID, an MRN, whatever you already store — and it is what Appendix deduplicates on, so keep it stable per patient. email is optional context for the reviewing physician; Appendix never sends to it.
curl -X POST https://api.appendix.com/api/v1/prescribing/patients \
-H "Authorization: Bearer ak_live_..." \
-H "Content-Type: application/json" \
-d '{
"first_name": "Dana",
"last_name": "Reyes",
"date_of_birth": "1991-04-22",
"sex": "female",
"state": "PA",
"zip": "19103",
"phone": "+14155550123",
"patient_ref": "acme-patient-88213",
"email": "dana.reyes@example.com",
"consent_attested": true,
"consent_reference": "acme-consent-88213"
}'{
"patient_id": "6f2d9c14-3b7e-4a21-9f08-1c5d2e8a4b60",
"first_name": "Dana",
"last_name": "Reyes",
"date_of_birth": "1991-04-22",
"sex": "female",
"state": "PA",
"zip": "19103",
"phone": "+14155550123",
"patient_ref": "acme-patient-88213",
"email": "dana.reyes@example.com",
"created_at": "2026-07-20T14:02:11Z",
"sandbox": false,
"external_consent": {
"attested_at": "2026-07-20T14:02:11Z",
"reference": "acme-consent-88213"
}
}Keep the patient_id. It is stable, and every future request for this person reuses it — replaying this call with the same patient_ref, name, and date of birth returns the same record with 200 rather than creating a duplicate.
2. Submit the clinical letter
/api/v1/prescribing/queryPass the patient_id instead of patient_* intake fields — the patient record already carries the demographics. external_id is your correlation ID, echoed back on webhooks and polling.
The clinical letter
The query field is a markdown clinical letter. In this example, your organization has synthesized the patient's acute complaint, medical history, and treatment guidelines into an integrated request for the physician to review.
# Chief Complaint
Right-sided facial pressure and purulent nasal discharge for 12 days, worsening after an initial improvement.
# Age and Sex
35-year-old female.
# History of Present Illness
Symptoms began 12 days ago as a typical viral upper respiratory infection: clear rhinorrhea, sneezing, mild sore throat, and low-grade fever to 99.8°F. She improved steadily through days 5-6 and considered herself nearly back to baseline. On day 8 symptoms worsened sharply and have not improved since: new thick yellow-green purulent discharge, right-sided maxillary facial pain and a new fever to 100.8°F two days ago. The discharge and pain are distinctly unilateral (right greater than left).
Conservative management over the past 7 days has failed: saline nasal irrigation twice daily, her usual intranasal fluticasone, pseudoephedrine 30 mg every 6 hours as needed, and ibuprofen 400 mg every 8 hours as needed. There has been no improvement at any point since the day 8 worsening.
No antibiotics in the past 6 weeks. No sick contacts outside the household, though both of her children had viral URIs in the past 3 weeks.
# Review of Systems
- Constitutional: Positive for subjective fever (maximum 100.8°F) and fatigue. Denies rigors or night sweats.
- HEENT: Positive for purulent right-sided nasal discharge, right maxillary pressure worse on bending forward, postnasal drip, hyposmia, and right upper molar ache. Denies ear pain or hearing change.
- Eyes: Denies periorbital swelling, periorbital erythema, vision change, diplopia, or pain with eye movement.
- Neuro: Denies severe or thunderclap headache, neck stiffness, photophobia, confusion, or focal deficits.
- Respiratory: Mild nighttime cough attributed to postnasal drip. Denies wheeze, dyspnea, or chest pain.
- GI: Denies nausea, vomiting, diarrhea, or abdominal pain.
# Past Medical History
- Type 2 diabetes mellitus, diagnosed 2021. Most recent A1c 6.8% (2026-05-14). No retinopathy, neuropathy, or nephropathy.
- Hypothyroidism secondary to Hashimoto thyroiditis, diagnosed 2016. TSH 2.1 mIU/L (2026-05-14), stable on the same dose for 3 years.
- Mild persistent asthma since childhood. Well controlled: no exacerbation since 2024, never hospitalized or intubated.
- Perennial allergic rhinitis. Managed with a daily intranasal corticosteroid.
- Prior acute sinusitis in 2019, resolved with a course of antibiotics. No chronic sinus disease, no nasal polyps, no prior sinus surgery.
- Surgical: laparoscopic cholecystectomy 2019.
- Obstetric: G2P2, both spontaneous vaginal deliveries. Last menstrual period 2026-07-08; copper IUD in place.
# Current Medications
- Metformin XR 1000 mg by mouth daily with dinner
- Levothyroxine 88 mcg by mouth daily
- Budesonide/formoterol 160/4.5 mcg, 2 inhalations twice daily
- Albuterol HFA 90 mcg, 2 puffs every 4-6 hours as needed (last used approximately 3 months ago)
- Fluticasone propionate nasal spray 50 mcg, 2 sprays each nostril daily
# Allergies
- Sulfamethoxazole/trimethoprim (sulfa): rash.
- No known penicillin or other beta-lactam allergy. No food, latex, or environmental drug allergies.
# Family History
Mother: type 2 diabetes, hypothyroidism. Father: hypertension. Sister: asthma and eczema. No family history of chronic rhinosinusitis or nasal polyposis.
# Social History
Non-smoker, never smoked, no vaping. Alcohol: 2-3 glasses of wine per week. No recreational drug use. Works as an elementary school teacher with high respiratory-illness exposure. Lives with spouse and two children (ages 4 and 7). No recent travel.
# Working Assessment
Acute bacterial rhinosinusitis, right maxillary. The presentation meets two of the three IDSA clinical criteria: symptoms persisting beyond 10 days without improvement, and "double worsening" — new fever, increased purulent discharge, and focal facial pain following a viral URI that had been improving. The unilateral purulent discharge and focal right maxillary tenderness support a bacterial rather than viral process. No red flags for orbital or intracranial complication: no periorbital swelling or erythema, no vision change, no diplopia, no severe headache, no neck stiffness, no altered mental status.
# Working Plan
Amoxicillin-clavulanate 875 mg/125 mg by mouth twice daily for 7 days — the IDSA first-line agent for adult acute bacterial rhinosinusitis.
Continue saline irrigation and intranasal fluticasone. Seek in-person or emergency evaluation for vision change, periorbital swelling, severe headache, neck stiffness, confusion, fever above 102°F, or failure to improve within 3-4 days.Every one of the required sections is present, and the negatives are explicit. Letter format has the full section list.
Sending it
# The letter above is saved as letter.md. Consider using jq to build the
# JSON so the markdown newlines are encoded correctly.
curl -X POST https://api.appendix.com/api/v1/prescribing/query \
-H "Authorization: Bearer ak_live_..." \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg patient_id "6f2d9c14-3b7e-4a21-9f08-1c5d2e8a4b60" \
--arg external_id "acme-req-4471" \
--rawfile query letter.md \
'{patient_id: $patient_id, external_id: $external_id, query: $query}')"{
"session_token": "st_9c41f2ab...",
"encounter_id": "b81c07f2-64d9-4e13-8a77-0f2b91c3de55",
"environment": "production",
"sandbox": false,
"final_decision_ready": true,
"status": "in_review",
"submission_id": "sub_4d81c9",
"next_steps": "..."
}No consent_url comes back, because there is no consent page to visit; this is unique to the enterprise workflow, and distinct from the patient consent modal described in Consent & Identity. The request goes straight into review: the patient's identity assurance is delegated to your organization by contract, so nothing pauses for verification.
If the letter is missing anything the physician would need, you get a completeness response instead. Gather the answers and resubmit with the same session_token. Nothing is billed until a physician completes a review.
{
"session_token": "st_9c41f2ab...",
"encounter_id": "b81c07f2-64d9-4e13-8a77-0f2b91c3de55",
"final_decision_ready": false,
"missing_items": [
"Allergies"
],
"commentary": "The letter does not state whether the patient has any drug allergies.",
"next_steps": "Please provide the missing information and resubmit with the same session_token."
}3. Read the interaction
/api/v1/prescribing/encounters/{id}/detailsPoll this, or wait for the encounter.message webhook to tell you a physician message is waiting. Here the physician has asked a follow-up question.
curl "https://api.appendix.com/api/v1/prescribing/encounters/b81c07f2-64d9-4e13-8a77-0f2b91c3de55/details" \
-H "Authorization: Bearer ak_live_..."{
"encounterId": "b81c07f2-64d9-4e13-8a77-0f2b91c3de55",
"externalId": "acme-req-4471",
"createdAt": "2026-07-20T14:03:40Z",
"sandbox": false,
"status": "in_review",
"dataVisibility": "full",
"dataSharingConsentAt": "2026-07-20T14:03:40Z",
"patient": {
"firstName": "Dana",
"lastName": "Reyes",
"dateOfBirth": "1991-04-22",
"sex": "female",
"state": "PA"
},
"clinicalLetter": "# Chief Complaint\nRight-sided facial pressure and purulent nasal discharge for 12 days...",
"submittedAt": "2026-07-20T14:03:40Z",
"conversation": [
{
"author": "clinician",
"clinicianName": "Sarah Chen, MD",
"message": "Thanks — this is a thorough history. Were you treated with amoxicillin-clavulanate (Augmentin) for your previous sinus infection?",
"createdAt": "2026-07-20T15:11:02Z"
}
],
"prescriptions": [],
"rxCount": 0
}4. Relay the patient's reply
/api/v1/prescribing/encounters/{id}/messagesYour app collected the answer in your own UI. Appendix stores it as a message authored by the patient and flags viaApp so the physician can see it arrived through your application rather than the Appendix chat page.
curl -X POST https://api.appendix.com/api/v1/prescribing/encounters/b81c07f2-64d9-4e13-8a77-0f2b91c3de55/messages \
-H "Authorization: Bearer ak_live_..." \
-H "Content-Type: application/json" \
-d '{
"message": "Yes, that was Augmentin in 2019 and I tolerated it fine, no rash or stomach trouble."
}'{
"messageId": "evt_7b3c9d10",
"createdAt": "2026-07-20T15:22:47Z",
"author": "patient",
"viaApp": true
}The encounter moves back to in_review and the physician is notified — exactly as if the patient had replied in the Appendix chat page themselves.
The completed request
When the physician finishes, your webhook fires encounter.completed. Fetch the details endpoint once more for the full record — the prescription is transmitted to the pharmacy by Appendix, and the patient receives a text message to choose one.
{
"encounterId": "b81c07f2-64d9-4e13-8a77-0f2b91c3de55",
"status": "completed",
"clinicalDecision": "rx_as_requested",
"conversation": [
{
"author": "clinician",
"clinicianName": "Sarah Chen, MD",
"message": "Thanks — this is a thorough history. Were you treated with amoxicillin-clavulanate (Augmentin) for your previous sinus infection?",
"createdAt": "2026-07-20T15:11:02Z"
},
{
"author": "patient",
"message": "Yes, that was Augmentin in 2019 and I tolerated it fine, no rash or stomach trouble.",
"createdAt": "2026-07-20T15:22:47Z",
"viaApp": true
},
{
"author": "clinician",
"clinicianName": "Sarah Chen, MD",
"message": "Sending amoxicillin-clavulanate 875/125 mg twice daily for 7 days to your pharmacy. Take it with food to ease the stomach. Keep up the saline rinses and the fluticasone. If you develop eye swelling, vision changes, a severe headache, or you are not improving in 3-4 days, get seen in person.",
"createdAt": "2026-07-20T15:31:18Z"
}
],
"clinicalDocumentation": [
{
"note": "Acute bacterial rhinosinusitis. 11 days of purulent nasal discharge, maxillary pressure, and congestion, with worsening after initial improvement — meets IDSA criteria for bacterial etiology rather than viral. No fever, periorbital swelling, vision change, or neurologic findings; no red flags for orbital or intracranial extension. Prior tolerance of amoxicillin-clavulanate confirmed with the patient, no penicillin allergy. First-line amoxicillin-clavulanate 875/125 mg BID x 7 days. Continue saline irrigation and intranasal fluticasone. Return precautions given for eye swelling, vision change, severe headache, or failure to improve in 3-4 days.",
"clinicianName": "Sarah Chen, MD",
"createdAt": "2026-07-20T15:31:11Z"
}
],
"prescriptions": [
{
"medication": "Amoxicillin-clavulanate 875 mg/125 mg tablet",
"quantity": "14 tablet",
"refills": 0,
"clinicianName": "Sarah Chen, MD",
"instructions": "Take 1 tablet by mouth twice daily for 7 days. Take with food.",
"createdAt": "2026-07-20T15:31:04Z"
}
],
"rxCount": 1
}clinicalDocumentation is the reviewing physician's own account of what they concluded and why — the clinical record of this request, in their words. If you hold the patient's broader record, this is the entry to file against it. Physicians sometimes document more than once on a request (an interim entry when they ask a follow-up question, then a final entry at completion), so treat it as an ordered list rather than a single field.
Your app is the only way back to the patient
Patients you create yourself are never emailed by Appendix and cannot sign in to the Appendix chat page — the address you submit is a record-keeping label, not a verified channel. So step 4 is the only way they can answer a physician's question. Build that relay before going live; chatUrl is not returned for these encounters, so there is nothing to surface. See Developer-Consented Patients for the tradeoffs.