---
title: "Get Appointments"
method: GET
path: "/dr/v1/appointment"
tags: ["Appointment API"]
---

# Get Appointments

`GET /dr/v1/appointment`

### Overview
This API endpoint is used to retrieve all the appointments scheduled for a business with flexible filters.
### Additional Information:

  - Valid filter combinations:
    1. `patient_id` (alone)
    2. `doctor_id`, `start_date`, `end_date`
    3. `clinic_id`, `start_date`, `end_date`
    4. `start_date`, `end_date`
    5. `doctor_id`, `clinic_id`, `start_date`, `end_date`
  - Dates must follow `YYYY-MM-DD` format.
  - The date range must not exceed **7 days**.
  - `end_date` cannot be before `start_date`.
  - There is a `limit` i.e the maximum number of appointments returned per page. The value of `limit` is automatically set based on the filters used:  
      - **20** → when filtering by `patient_id` (alone).  
      - **50** → when filtering by (`doctor_id`, `start_date`, `end_date`) OR (`clinic_id`, `start_date`, `end_date`) OR (`doctor_id`, `clinic_id`, `start_date`, `end_date`).  
      - **30** → when filtering only by (`start_date`, `end_date`).  

### Appointment_statuses:

      Booked / Queue States:
        - BK (Booked) : Appointment created/confirmed.
        - CK (Checked-in) : Booked appointment added to the Queue (Checked-in).
        - RV (Reserved) : Appointment marked as Reserved, when patient said they will come for the appointment on the follow-up appointment message.
        - IN (Initiated) : Appointment marked as Initiated, when patient received follow-up appointment message.
        - PA  (Parked) : Appointment moved to Parked state.

      Ongoing States:
        - OG (Ongoing): Consultation is in progress.

      Completion Statuses:
        - CM (Completed): Appointment completed with a prescription created.
        - CMNP (Completed No Prescription) : Appointment marked Exit from Queue / Completed without a prescription.
        - AB (Aborted) : Appointment was started (Start Visit) but not completed. Automatically marked AB at 12:00 AM next day.
        - NS (No Show) : Appointment was added to Queue but not started/completed. Automatically marked NS at 12:00 AM next day.
        - NSD (No Show Doctor) : No-show tagged specifically from a doctor’s action (if implemented).
        - NSS (No Show Staff) : No-show tagged specifically from a staff action (if implemented).

      Cancellation Statuses:
        - CN (Cancelled) : Appointment cancelled via API.
        - CND (Cancelled Doctor) : Cancelled from the doctor’s account in the tool.
        - CNS (Cancelled Staff) : Cancelled from the staff’s account in the tool.
        - PC (Provisional Cancelled) : Appointment marked as provisional cancellation, when patient said they will not come for the appointment on the follow-up appointment message.
        - PNR (Payment Not Received) : Appointment marked as PNR, when patient tried paying for a pre-paid appointment but the payment failed.

      Reschedule Statuses:
        - RE : Rescheduled via API.
        - RES : Rescheduled from staff account.
        - RED : Rescheduled from doctor account.

## Query parameters

- `patient_id` string
- `doctor_id` string
- `clinic_id` string
- `start_date` string, date
- `end_date` string, date
- `page_no` integer

## Headers

- `Authorization` string, required

## Response `200`

Successful response with appointment list

- object
  - `appointments` object[]
    - `appointment_id` string
    - `created_at` integer
    - `doctor_id` string
    - `patient_id` string
    - `clinic_id` string
    - `channel` string
    - `status` 'BK' | 'OG' | 'CM' | 'CMNP' | 'CN' | 'CND' | 'CNS'
    - `mode` 'tele' | 'in_clinic'
    - `start_time` integer
    - `end_time` integer
    - `prescription_id` string
    - `prescription_url` string
    - `partner_appointment_id` string
    - `partner_clinic_id` string
    - `partner_doctor_id` string
    - `partner_patient_id` string

## Other responses

- `400` — Invalid request (validation error)
- `403` — Forbidden (no permission to access resource)
- `500` — Internal Server Error

---

[API](https://skmtc.net/eka/apis/eka-developer-apis.md) · [All operations](https://skmtc.net/eka/apis/eka-developer-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eka/eka-developer-apis/revisions/9ea23456f722/schema)