Notifications

The Notifications API enables multi-channel communication with patients and providers. Send appointment reminders, lab result alerts, prescription notifications, and more via SMS, Email, Push, and WhatsApp.

Trigger Endpoints

Use these pre-built trigger endpoints for common notification types:

POST/api/v1/triggers/appointment-reminder/Send appointment reminder

POST/api/v1/triggers/lab-result/Notify lab results ready

POST/api/v1/triggers/critical-alert/Critical lab value alert

POST/api/v1/triggers/prescription-ready/Prescription ready notification

POST/api/v1/triggers/delivery-status/Delivery status update

POST/api/v1/triggers/care-plan-update/Care plan update notification

POST/api/v1/triggers/payment-reminder/Payment reminder

Appointment Reminder

Send an appointment reminder to a patient via their preferred channels.

POST/api/v1/triggers/appointment-reminder/

Request Body

patient_uhidstringrequired

Patient UHID

appointment_idstringrequired

Appointment ID

provider_namestringrequired

Healthcare provider name

facility_namestringrequired

Facility name

appointment_datedatetimerequired

Appointment date/time (ISO 8601)

appointment_typestringoptional

Type of appointment

notesstringoptional

Additional notes for patient

Request

bash

curl -X POST https://api.mediloop.co/api/v1/triggers/appointment-reminder/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "appointment_id": "apt-123-456",
    "provider_name": "Dr. Sarah Nakamya",
    "facility_name": "Mulago Hospital",
    "appointment_date": "2024-01-20T10:00:00Z",
    "appointment_type": "General Consultation",
    "notes": "Please bring previous test results"
  }'

RESPONSE200

{
  "success": true,
  "notification_id": "notif-550e8400-e29b-41d4",
  "notification_number": "NOTIF-20240115-0001"
}

Lab Result Ready

Notify a patient that their lab results are ready for viewing.

POST/api/v1/triggers/lab-result/

Request Body

patient_uhidstringrequired

Patient UHID

observation_idstringrequired

Lab observation ID

test_namestringrequired

Name of the test

ordered_bystringrequired

Ordering provider name

facility_namestringrequired

Lab facility name

Request

bash

curl -X POST https://api.mediloop.co/api/v1/triggers/lab-result/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "observation_id": "obs-789-012",
    "test_name": "Complete Blood Count",
    "ordered_by": "Dr. James Okello",
    "facility_name": "Lancet Laboratories"
  }'

RESPONSE200

{
  "success": true,
  "notification_id": "notif-660f9500-f30c-52e5",
  "notification_number": "NOTIF-20240115-0002"
}

Critical Lab Value Alert

Send urgent notification for critical lab values. This notifies BOTH the patient and their provider. Critical alerts bypass quiet hours and consent preferences.

POST/api/v1/triggers/critical-alert/

Request Body

patient_uhidstringrequired

Patient UHID

provider_idstringrequired

Provider ID to notify

observation_idstringrequired

Lab observation ID

test_namestringrequired

Name of the test

valuestringrequired

Critical value

unitstringrequired

Unit of measurement

reference_rangestringrequired

Normal reference range

patient_namestringrequired

Patient name (for provider notification)

Request

bash

curl -X POST https://api.mediloop.co/api/v1/triggers/critical-alert/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "provider_id": "prov-abc-123",
    "observation_id": "obs-critical-001",
    "test_name": "Blood Glucose",
    "value": "350",
    "unit": "mg/dL",
    "reference_range": "70-100 mg/dL",
    "patient_name": "John Doe"
  }'

RESPONSE200

{
  "success": true,
  "notifications_created": 2,
  "notification_ids": [
    "notif-patient-001",
    "notif-provider-001"
  ]
}

Prescription Ready

Notify a patient that their prescription is ready. Note: MediLoop is a marketplace - patients can purchase from any participating pharmacy.

POST/api/v1/triggers/prescription-ready/

Request Body

patient_uhidstringrequired

Patient UHID

prescription_idstringrequired

Prescription ID

medication_namestringrequired

Medication name

prescriber_namestringrequired

Prescribing provider

facility_namestringrequired

Prescribing facility

instructionsstringoptional

Dosage instructions

Request

bash

curl -X POST https://api.mediloop.co/api/v1/triggers/prescription-ready/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "prescription_id": "rx-456-789",
    "medication_name": "Amoxicillin 500mg",
    "prescriber_name": "Dr. Sarah Nakamya",
    "facility_name": "Mulago Hospital",
    "instructions": "Take 3 times daily with food for 7 days"
  }'

RESPONSE200

{
  "success": true,
  "notification_id": "notif-rx-001",
  "notification_number": "NOTIF-20240115-0003"
}

Delivery Status Update

Notify a patient about their delivery status (medication delivery, specimen collection, etc.).

POST/api/v1/triggers/delivery-status/

Request Body

patient_uhidstringrequired

Patient UHID

delivery_idstringrequired

Delivery order ID

statusstringrequired

Delivery status

delivery_typestringrequired

Type: medication, specimen, equipment

estimated_timestringoptional

Estimated delivery time

courier_namestringoptional

Courier name

courier_phonestringoptional

Courier phone

Request

bash

curl -X POST https://api.mediloop.co/api/v1/triggers/delivery-status/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "delivery_id": "del-123-456",
    "status": "out_for_delivery",
    "delivery_type": "medication",
    "estimated_time": "30 minutes",
    "courier_name": "James",
    "courier_phone": "+256700555666"
  }'

RESPONSE200

{
  "success": true,
  "notification_id": "notif-del-001",
  "notification_number": "NOTIF-20240115-0004"
}

Notification Channels

Notifications are sent via the patient's preferred channels:

Channel	Description	Cost (UGX)
`SMS`	Text message via Africa's Talking	80
`EMAIL`	Email via AWS SES	20
`PUSH`	Mobile push notification	Free
`WHATSAPP`	WhatsApp message	200

Notification Status

Status	Description
`PENDING`	Queued for processing
`PROCESSING`	Currently being sent
`SENT`	Sent to provider
`DELIVERED`	Confirmed delivered
`FAILED`	Delivery failed
`CANCELLED`	Cancelled before sending