Patient engagement, as an API.

• messaging.send_smsSingle SMS to one patient by id, MRN, or last-4 phone
• messaging.send_emailTemplated email with merge fields and tracking
• messaging.scheduleQueue a message for future delivery; respects clinic quiet hours
• messaging.bulk_sendCampaign send to a filtered patient list (rate-limit gated)
• messaging.predefined_listPull the clinic’s approved message templates

POST /v1/messaging/send_sms
Authorization: Bearer eyJ...
{
  "patient_id": "p_2k7f...",
  "template_id": "tmpl_visit_followup",
  "variables": { "next_appt": "Tue 9am" },
  "send_at": "2026-05-02T14:00:00Z"
}

• messages.listRecent messages, paginated, filterable by direction or thread
• messages.unread_countInbox badge counter for staff-side dashboards
• messages.mark_readMark a thread or message read
• messages.triage_acceptPull a triage-queued message and start working it
• messages.assignAssign a thread to a specific staff user
• messages.delivery_statusFinal delivery state for any sent message

GET /v1/messages?direction=inbound&unread=true&limit=50
Authorization: Bearer eyJ...

{
  "messages": [
    {
      "id": "msg_...", "thread_id": "thr_...",
      "patient_id": "p_...", "channel": "sms",
      "direction": "inbound", "received_at": "...",
      "preview": "I need to reschedule my Thursday..."
    }
  ],
  "next_cursor": "..."
}

• surveys.sendQueue a survey to a patient over their preferred channel
• surveys.list_responsesPull responses with score, free-text, and AI summary
• surveys.get_responseFull detail for a single response, including AI sentiment
• surveys.summarizeAI-summarized roll-up by provider, location, or period
• surveys.subscribe_webhookGet notified on every completion (signed HMAC-SHA256)

POST /v1/surveys/send
Authorization: Bearer eyJ...
{
  "patient_id": "p_...",
  "template": "post_visit_nps",
  "delay_minutes": 60,
  "channel": "sms"
}

• recare.list_rulesAll recare rules currently active for the clinic
• recare.get_ruleDetail for a specific rule including match criteria
• recare.create_ruleDefine a new rule programmatically (subject to scope)
• recare.list_overduePatients currently flagged overdue by any active rule
• recare.triggerManually fire a rule for a specific patient or cohort

GET /v1/recare/list_overdue?rule_id=rule_diab_a1c
Authorization: Bearer eyJ...

{ "patients": [
    { "patient_id": "p_...", "last_visit": "2025-08-14",
      "days_overdue": 89, "matched_criteria": ["A1c > 9", "T2DM"] }
  ] }

• appointments.listFiltered list (date, provider, location, status)
• appointments.unconfirmedJust the appointments still awaiting confirmation
• appointments.confirmRecord a confirmation through any channel (Phase 2)
• appointments.mark_no_showMark a no-show, optionally trigger no-show messaging
• appointments.queue_no_show_messagesSend the clinic’s configured no-show follow-up
• appointments.appointment_typesPractice’s appointment-type catalog with durations

GET /v1/appointments/unconfirmed?date=2026-05-02
Authorization: Bearer eyJ...

{ "appointments": [
    { "id": "apt_...", "patient_id": "p_...",
      "provider_id": "prv_...", "starts_at": "...",
      "appointment_type": "Annual Wellness",
      "reminder_attempts": 2 }
  ] }

• messages.delivery_statusFinal state by message id (sent, delivered, failed, opted-out)
• messages.listAll messages with delivery status filterable by date and channel
• reports.confirmation_chartAggregate confirmations by method (SMS, voice, email, manual)
• reports.communication_summaryVolume + outcomes by channel for any period
• webhooks.message.deliveredPush notification on each delivery (Phase 2)
• webhooks.message.failedPush notification with failure reason (Phase 2)

GET /v1/messages/msg_92b.../delivery_status
Authorization: Bearer eyJ...

{ "message_id": "msg_92b...",
  "channel": "sms",
  "status": "delivered",
  "queued_at": "2026-05-01T08:00Z",
  "delivered_at": "2026-05-01T08:00:14Z",
  "carrier": "T-Mobile",
  "patient_replied": false }

• waitlist.listCurrent waitlist entries, paginated
• waitlist.add_patientAdd a patient with their preferences and constraints
• waitlist.remove_patientRemove (e.g., after they get scheduled elsewhere)
• waitlist.trigger_matchFire the match engine for an open slot
• waitlist.view_claimSee which patient claimed which slot
• webhooks.waitlist.claimedPush notification on claim (Phase 2)

POST /v1/waitlist/trigger_match
Authorization: Bearer eyJ...
{
  "appointment_type": "Annual Wellness",
  "provider_id": "prv_...",
  "slot_starts_at": "2026-05-03T14:00Z",
  "slot_duration_minutes": 30,
  "max_candidates": 25
}

• forms.list_submissionsFilterable by date, status, patient, or form type
• forms.get_submission_detailsStructured field-by-field submission data
• forms.send_to_patientPush a form by SMS or email (Phase 2)
• forms.get_pdfFinal PDF for chart attachment
• forms.batch_downloadMulti-submission PDF bundle
• forms.mark_doneClose out a submission once reviewed
• webhooks.form.submittedPush notification on completion (Phase 2)

POST /v1/forms/send_to_patient
Authorization: Bearer eyJ...
{
  "patient_id": "p_...",
  "form_id": "frm_new_patient_intake",
  "channel": "sms",
  "due_at": "2026-05-02T08:00Z"
}