Appointments API

2026-02-01 · 4 min

Overview

The Appointments API enables scheduling, rescheduling, and cancellation of appointments. Use it to integrate online booking from your website, mobile app, or third-party aggregators with Bio Ecko's appointment system.

List Available Slots

GET /api/v1/appointments/slots

Query parameters:

• doctor_id (string, required): The doctor to check slots for.
• date (date, required): The date to check (YYYY-MM-DD).
• branch_id (string): Filter by branch (required for multi-branch setups).
• duration (int): Slot duration in minutes, defaults to doctor's configured slot duration.

Response: Array of available time slots with start_time and end_time. Requires appointments:read scope.

Book Appointment

POST /api/v1/appointments

Request body: { "patient_id": "PAT-2026-00123", "doctor_id": "DOC-001", "branch_id": "MUM-01", "slot_start": "2026-03-15T10:00:00+05:30", "slot_end": "2026-03-15T10:15:00+05:30", "visit_type": "new_consultation", "notes": "Patient reports persistent cough" }

Response: Created appointment object with appointment_id, token_number, and status. Requires appointments:write scope.

Reschedule & Cancel

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

Request body: { "new_slot_start": "...", "new_slot_end": "...", "reason": "Patient requested" }

DELETE /api/v1/appointments/{id} Query parameter: reason (string, required).

Both operations trigger patient notifications if notifications are configured. Cancellation within the configured window (e.g., 2 hours) may be restricted.

Webhooks

Subscribe to appointment events:

• appointment.booked: Fired when a new appointment is created.
• appointment.rescheduled: Fired when an appointment time changes.
• appointment.cancelled: Fired when an appointment is cancelled.
• appointment.checked_in: Fired when the patient arrives.
• appointment.completed: Fired when the visit is completed.

Webhook payloads include the full appointment object. Configure webhook URLs under Admin > Settings > API > Webhooks.

Notes

Related topics