Appointments

The Appointments API allows you to book, manage, and track patient appointments with healthcare providers. Appointments are linked to patients via UHID and support various service types, specialties, and scheduling workflows.

Endpoints

POST/api/v1/appointments/Book an appointment

GET/api/v1/appointments/List appointments

GET/api/v1/appointments/{id}/Get appointment details

GET/api/v1/appointments/availability/Search available slots

GET/api/v1/appointments/by-patient/Get patient appointments

GET/api/v1/appointments/by-practitioner/Get practitioner appointments

POST/api/v1/appointments/{id}/cancel/Cancel appointment

POST/api/v1/appointments/{id}/reschedule/Reschedule appointment

POST/api/v1/appointments/{id}/check-in/Check in patient

POST/api/v1/appointments/{id}/arrived/Mark patient arrived

POST/api/v1/appointments/{id}/fulfilled/Mark appointment complete

POST/api/v1/appointments/{id}/noshow/Mark no-show

The Appointment Object

Attributes

iduuid

Unique identifier for the appointment.

appointment_numberstring

Human-readable appointment reference.

patient_uhidstring

UHID of the patient.

patient_namestring

Patient full name.

practitioner_iduuid

ID of the healthcare provider.

practitioner_namestring

Provider full name.

facility_iduuidnullable

ID of the facility.

facility_namestringnullable

Facility name.

statusstring

Appointment status (see status values below).

service_type_codestring

Type of service (e.g., consultation).

specialty_codestringnullable

Medical specialty code.

appointment_type_codestring

ROUTINE, WALKIN, CHECKUP, FOLLOWUP, EMERGENCY.

start_timedatetime

Scheduled start time (ISO 8601).

end_timedatetime

Scheduled end time (ISO 8601).

duration_minutesinteger

Duration in minutes.

reason_textstringnullable

Reason for the appointment.

priorityinteger

Priority (1-10, lower is higher priority).

patient_instructionstringnullable

Instructions for the patient.

notesstringnullable

Internal notes.

created_atdatetime

When the appointment was created.

RESPONSE200

{
  "id": "apt-123-456-789",
  "appointment_number": "APT-2024-001234",
  "patient_uhid": "UG123456789A",
  "patient_name": "John Doe",
  "practitioner_id": "prov-abc-123",
  "practitioner_name": "Dr. Sarah Nakamya",
  "facility_id": "fac-xyz-789",
  "facility_name": "Mulago Hospital",
  "status": "booked",
  "service_type_code": "consultation",
  "specialty_code": "general-practice",
  "appointment_type_code": "ROUTINE",
  "start_time": "2024-01-20T10:00:00Z",
  "end_time": "2024-01-20T10:30:00Z",
  "duration_minutes": 30,
  "reason_text": "General checkup",
  "priority": 5,
  "patient_instruction": "Please bring previous test results",
  "created_at": "2024-01-15T10:00:00Z"
}

Book an Appointment

Creates a new appointment for a patient with a healthcare provider.

POST/api/v1/appointments/

Request Body

patient_uhidstringrequired

UHID of the patient

practitioner_iduuidrequired

ID of the healthcare provider

service_type_codestringrequired

Type of service

start_timedatetimerequired

Start time (ISO 8601)

end_timedatetimeoptional

End time (calculated from duration if not provided)

duration_minutesintegeroptional

Duration in minutes

Default: 30

slot_iduuidoptional

Pre-selected slot ID

facility_iduuidoptional

Facility ID

specialty_codestringoptional

Medical specialty

appointment_type_codestringoptional

Appointment type

Default: ROUTINE

reason_textstringoptional

Reason for visit

priorityintegeroptional

Priority (1-10)

Default: 5

patient_instructionstringoptional

Instructions for patient

notesstringoptional

Internal notes

Request

bash

curl -X POST https://api.mediloop.co/api/v1/appointments/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "practitioner_id": "prov-abc-123",
    "service_type_code": "consultation",
    "start_time": "2024-01-20T10:00:00Z",
    "duration_minutes": 30,
    "facility_id": "fac-xyz-789",
    "reason_text": "General checkup"
  }'

RESPONSE201

{
  "id": "apt-123-456-789",
  "appointment_number": "APT-2024-001234",
  "patient_uhid": "UG123456789A",
  "status": "booked",
  "start_time": "2024-01-20T10:00:00Z",
  "end_time": "2024-01-20T10:30:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

List Appointments

Returns a filtered list of appointments.

GET/api/v1/appointments/

Query Parameters

statusstringoptional

Filter by status

patient_uhidstringoptional

Filter by patient UHID

practitioner_iduuidoptional

Filter by practitioner

facility_iduuidoptional

Filter by facility

date_fromdateoptional

Filter from date

date_todateoptional

Filter to date

upcoming_onlybooleanoptional

Only show upcoming appointments

Request

bash

curl "https://api.mediloop.co/api/v1/appointments/?patient_uhid=UG123456789A&upcoming_only=true" \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "count": 1,
  "results": [
    {
      "id": "apt-123-456-789",
      "appointment_number": "APT-2024-001234",
      "patient_uhid": "UG123456789A",
      "status": "booked",
      "start_time": "2024-01-20T10:00:00Z"
    }
  ]
}

Check Availability

Search for available appointment slots based on criteria.

GET/api/v1/appointments/availability/

Query Parameters

date_fromdaterequired

Start date for search

date_todaterequired

End date for search

practitioner_iduuidoptional

Filter by practitioner

facility_iduuidoptional

Filter by facility

service_typestringoptional

Filter by service type

specialtystringoptional

Filter by specialty

duration_minutesintegeroptional

Minimum slot duration needed

Request

bash

curl "https://api.mediloop.co/api/v1/appointments/availability/?date_from=2024-01-20&date_to=2024-01-25&specialty=general-practice" \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "count": 3,
  "results": [
    {
      "id": "slot-001",
      "practitioner_id": "prov-abc-123",
      "practitioner_name": "Dr. Sarah Nakamya",
      "facility_name": "Mulago Hospital",
      "start_time": "2024-01-20T09:00:00Z",
      "end_time": "2024-01-20T09:30:00Z",
      "status": "free"
    },
    {
      "id": "slot-002",
      "practitioner_id": "prov-abc-123",
      "practitioner_name": "Dr. Sarah Nakamya",
      "facility_name": "Mulago Hospital",
      "start_time": "2024-01-20T10:00:00Z",
      "end_time": "2024-01-20T10:30:00Z",
      "status": "free"
    }
  ]
}

Cancel Appointment

Cancels an existing appointment.

POST/api/v1/appointments/{id}/cancel/

Request Body

cancellation_reason_codestringrequired

Reason code for cancellation

cancellation_reason_textstringoptional

Additional explanation

Request

bash

curl -X POST https://api.mediloop.co/api/v1/appointments/apt-123-456-789/cancel/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason_code": "patient-request",
    "cancellation_reason_text": "Patient unable to attend"
  }'

RESPONSE200

{
  "id": "apt-123-456-789",
  "status": "cancelled",
  "cancellation_reason_code": "patient-request",
  "cancellation_reason_text": "Patient unable to attend",
  "cancelled_at": "2024-01-18T14:00:00Z"
}

Reschedule Appointment

Reschedules an appointment to a new time.

POST/api/v1/appointments/{id}/reschedule/

Request Body

new_start_timedatetimerequired

New start time

new_end_timedatetimeoptional

New end time

new_slot_iduuidoptional

New slot ID if using slots

reasonstringoptional

Reason for rescheduling

Request

bash

curl -X POST https://api.mediloop.co/api/v1/appointments/apt-123-456-789/reschedule/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "new_start_time": "2024-01-22T14:00:00Z",
    "reason": "Provider schedule conflict"
  }'

RESPONSE200

{
  "id": "apt-123-456-789",
  "status": "booked",
  "start_time": "2024-01-22T14:00:00Z",
  "end_time": "2024-01-22T14:30:00Z",
  "rescheduled_at": "2024-01-18T14:00:00Z"
}

Appointment Status Values

Status	Description
`proposed`	Appointment has been proposed but not confirmed
`pending`	Awaiting confirmation
`booked`	Appointment is confirmed
`arrived`	Patient has arrived at the facility
`checked-in`	Patient has checked in
`fulfilled`	Appointment completed successfully
`cancelled`	Appointment was cancelled
`noshow`	Patient did not show up

Appointment Types

Type	Description
`ROUTINE`	Standard scheduled appointment
`WALKIN`	Walk-in appointment
`CHECKUP`	Regular health checkup
`FOLLOWUP`	Follow-up from previous visit
`EMERGENCY`	Emergency appointment