API reference

Appointments & queue

Doctors, their weekly timings, appointments and the live OPD queue. Everything you need for website booking or a front-desk bot.

List doctors

GET/api/v1/usersScope: appointments:read

The clinic's doctors, with the IDs you need for booking. The role=doctor filter is required for API keys.

Field	Where	Type	Description
`role`required	after ?	string	Must be doctor.

Example request

bash

curl "https://your-healthfix-site/api/v1/users?role=doctor" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

json

{
  "data": [
    { "id": "5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d", "full_name": "Dr. Asha Mehta", "role": "doctor", "specialization": "Cardiology", "is_active": true, "…": "…" }
  ]
}

Doctors' timings and leave

GET/api/v1/schedulesScope: appointments:read

Each doctor's weekly sessions (day and hours) and current or upcoming leave. Use it to show when booking is possible.

Example request

bash

curl "https://your-healthfix-site/api/v1/schedules" \
  -H "Authorization: Bearer YOUR_API_KEY"

List appointments

GET/api/v1/appointmentsScope: appointments:read

Appointments between two moments, up to 62 days apart. Without from and to you get today (UTC).

Field	Where	Type	Description
`from`	after ?	datetime	Start, e.g. 2026-10-01T00:00:00+05:30.
`to`	after ?	datetime	End (not included). Default: 24 hours after from.
`doctor_id`	after ?	uuid	Only this doctor.
`status`	after ?	string	scheduled, checked_in, in_consultation, completed, cancelled or no_show.
`branch_id`	after ?	uuid	Only this branch (multi-location clinics).

Example request

bash

curl "https://your-healthfix-site/api/v1/appointments?from=2026-10-01T00:00:00%2B05:30&to=2026-10-02T00:00:00%2B05:30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

json

{ "data": [ { "id": "9c8b7a6d-5e4f-4321-9abc-def012345678", "patient_name": "Ravi Kumar", "doctor_name": "Dr. Asha Mehta", "scheduled_at": "2026-10-01T05:00:00Z", "status": "scheduled", "…": "…" } ] }

In a URL, write + as %2B, as in the example.

Get an appointment

GET/api/v1/appointments/{id}Scope: appointments:read

One appointment with patient, doctor, status, token and timings.

Field	Where	Type	Description
`id`required	in the path	uuid	The appointment's ID.

Example request

bash

curl "https://your-healthfix-site/api/v1/appointments/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

json

{
  "data": {
    "id": "9c8b7a6d-5e4f-4321-9abc-def012345678",
    "patient_id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_name": "Ravi Kumar",
    "patient_code": "CHC000123",
    "patient_phone": "9876501234",
    "doctor_id": "5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d",
    "doctor_name": "Dr. Asha Mehta",
    "scheduled_at": "2026-10-01T05:00:00Z",
    "duration_min": 15,
    "status": "scheduled",
    "reason": "Follow-up",
    "notes": null,
    "is_walk_in": false,
    "source": "staff",
    "mode": "in_person",
    "video_url": null,
    "token_no": null,
    "checked_in_at": null,
    "started_at": null,
    "completed_at": null
  }
}

A patient's appointments

GET/api/v1/patients/{id}/appointmentsScope: appointments:read

Past and upcoming appointments for one patient, newest first.

Field	Where	Type	Description
`id`required	in the path	uuid	The patient's ID.
`limit`	after ?	integer	Default 20, max 100.

Example request

bash

curl "https://your-healthfix-site/api/v1/patients/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY"

OPD queue

GET/api/v1/queueScope: appointments:read

The day's queue: every appointment with token number, position, waiting time, plus totals.

Field	Where	Type	Description
`date`	after ?	date	YYYY-MM-DD. Default today in the clinic's time zone.
`doctor_id`	after ?	uuid	Only this doctor's queue.
`branch_id`	after ?	uuid	Only this branch.

Example request

bash

curl "https://your-healthfix-site/api/v1/queue" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

json

{
  "data": {
    "date": "2026-10-01",
    "now": "2026-10-01T05:12:00Z",
    "items": [
      { "id": "9c8b7a6d-5e4f-4321-9abc-def012345678", "patient_name": "Ravi Kumar", "token_no": 7, "status": "checked_in", "position": 2, "wait_min": 11, "…": "…" }
    ],
    "stats": { "total": 18, "waiting": 3, "in_consultation": 1, "completed": 9, "avg_wait_min": 14, "…": "…" }
  }
}

Book an appointment

POST/api/v1/appointmentsScope: appointments:write

Books a patient with a doctor. Fails with 409 if it overlaps another appointment of that doctor. Check the doctor's timings and leave (Doctors' timings) before offering a time.

Field	Where	Type	Description
`patient_id`required	JSON body	uuid	From Search patients or Register a patient.
`doctor_id`required	JSON body	uuid	From List doctors.
`scheduled_at`required	JSON body	datetime	Start time with time zone, e.g. 2026-10-01T10:30:00+05:30.
`duration_min`required	JSON body	integer	Length in minutes, 5 to 240. 15 is typical.
`mode`	JSON body	string	in_person (default) or video (needs the telehealth module).
`reason`	JSON body	string	Reason for the visit, up to 500 characters.
`notes`	JSON body	string	Notes for the front desk, up to 2000 characters.
`branch_id`	JSON body	uuid	Branch; default is the doctor's home branch.

Example request

bash

curl -X POST "https://your-healthfix-site/api/v1/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"patient_id":"0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42","doctor_id":"5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d","scheduled_at":"2026-10-01T10:30:00+05:30","duration_min":15,"reason":"Follow-up"}'

Example response

json

{
  "data": {
    "id": "9c8b7a6d-5e4f-4321-9abc-def012345678",
    "patient_id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_name": "Ravi Kumar",
    "patient_code": "CHC000123",
    "patient_phone": "9876501234",
    "doctor_id": "5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d",
    "doctor_name": "Dr. Asha Mehta",
    "scheduled_at": "2026-10-01T05:00:00Z",
    "duration_min": 15,
    "status": "scheduled",
    "reason": "Follow-up",
    "notes": null,
    "is_walk_in": false,
    "source": "staff",
    "mode": "in_person",
    "video_url": null,
    "token_no": null,
    "checked_in_at": null,
    "started_at": null,
    "completed_at": null
  }
}

Returns 201 Created. The appointment appears in the app and the patient gets the usual reminders.

Reschedule an appointment

PUT/api/v1/appointments/{id}Scope: appointments:write

Moves an appointment (and can change the doctor or length). Send all the booking fields, not just the changed ones.

Field	Where	Type	Description
`id`required	in the path	uuid	The appointment's ID.
`…`	JSON body		Same fields as Book an appointment.

Example request

bash

curl -X PUT "https://your-healthfix-site/api/v1/appointments/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"patient_id":"0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42","doctor_id":"5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d","scheduled_at":"2026-10-02T11:00:00+05:30","duration_min":15,"reason":"Follow-up"}'

Example response

json

{
  "data": {
    "id": "9c8b7a6d-5e4f-4321-9abc-def012345678",
    "patient_id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_name": "Ravi Kumar",
    "patient_code": "CHC000123",
    "patient_phone": "9876501234",
    "doctor_id": "5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d",
    "doctor_name": "Dr. Asha Mehta",
    "scheduled_at": "2026-10-01T05:00:00Z",
    "duration_min": 15,
    "status": "scheduled",
    "reason": "Follow-up",
    "notes": null,
    "is_walk_in": false,
    "source": "staff",
    "mode": "in_person",
    "video_url": null,
    "token_no": null,
    "checked_in_at": null,
    "started_at": null,
    "completed_at": null
  }
}

Check in, cancel or change status

PATCH/api/v1/appointments/{id}/statusScope: appointments:write

Moves an appointment along: scheduled → checked_in → in_consultation → completed, or to cancelled / no_show. Impossible moves (like completed → scheduled) return 409.

Field	Where	Type	Description
`id`required	in the path	uuid	The appointment's ID.
`status`required	JSON body	string	scheduled, checked_in, in_consultation, completed, cancelled or no_show.

Example request

bash

curl -X PATCH "https://your-healthfix-site/api/v1/appointments/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"checked_in"}'

Example response

json

{
  "data": {
    "id": "9c8b7a6d-5e4f-4321-9abc-def012345678",
    "patient_id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_name": "Ravi Kumar",
    "patient_code": "CHC000123",
    "patient_phone": "9876501234",
    "doctor_id": "5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d",
    "doctor_name": "Dr. Asha Mehta",
    "scheduled_at": "2026-10-01T05:00:00Z",
    "duration_min": 15,
    "status": "checked_in",
    "reason": "Follow-up",
    "notes": null,
    "is_walk_in": false,
    "source": "staff",
    "mode": "in_person",
    "video_url": null,
    "token_no": 7,
    "checked_in_at": null,
    "started_at": null,
    "completed_at": null
  }
}

Add a walk-in

POST/api/v1/appointments/walk-inScope: appointments:write

Adds a patient to today's queue right now and gives them the next token number.

Field	Where	Type	Description
`patient_id`required	JSON body	uuid	The patient.
`doctor_id`required	JSON body	uuid	The doctor they'll see.
`reason`	JSON body	string	Reason for the visit.
`notes`	JSON body	string	Notes for the front desk.
`branch_id`	JSON body	uuid	Branch, for multi-location clinics.

Example request

bash

curl -X POST "https://your-healthfix-site/api/v1/appointments/walk-in" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"patient_id":"0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42","doctor_id":"5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d","reason":"Fever since 2 days"}'

Example response

json

{
  "data": {
    "id": "9c8b7a6d-5e4f-4321-9abc-def012345678",
    "patient_id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_name": "Ravi Kumar",
    "patient_code": "CHC000123",
    "patient_phone": "9876501234",
    "doctor_id": "5a1d2c3b-7e6f-4a9b-8c0d-1e2f3a4b5c6d",
    "doctor_name": "Dr. Asha Mehta",
    "scheduled_at": "2026-10-01T05:00:00Z",
    "duration_min": 15,
    "status": "checked_in",
    "reason": "Follow-up",
    "notes": null,
    "is_walk_in": true,
    "source": "staff",
    "mode": "in_person",
    "video_url": null,
    "token_no": 8,
    "checked_in_at": null,
    "started_at": null,
    "completed_at": null
  }
}