Public booking API endpoints

The booking API provides the endpoints that power the patient-facing online booking widget. All endpoints in this group are public — they do not require Authorization or x-clinic-id headers. Patients can discover a clinic by its slug, browse available services and doctors, check available time slots, and submit a booking, all without having a CitaBox account.

All endpoints documented on this page are public. Do not include Authorization or x-clinic-id headers when calling them. Including those headers is harmless but unnecessary.

Booking flow

The endpoints must be called in the following sequence to complete a booking:

Fetch clinic information

Call GET /public/clinics/:slug to load the clinic’s public profile, confirm booking is enabled, and obtain the clinic_id needed for subsequent requests.

Fetch available services

Call GET /booking/services?clinic_id= to list the services the clinic offers. Optionally filter by doctor_id if the patient has a preferred doctor.

Fetch available doctors

Call GET /booking/doctors?clinic_id=&service_id= to list doctors who provide the selected service. The patient may choose a specific doctor or leave selection open.

Fetch available time slots

Call GET /booking/available-slots?clinic_id=&date=&service_id= to retrieve available slots for the chosen date. Pass doctor_id to filter by a specific doctor. When doctor_id is omitted or set to any, the backend merges slots across all eligible doctors and attaches a doctor_id to each available slot.

Submit the booking

Call POST /booking/appointments with the patient’s personal details and the chosen slot to create the appointment and receive a confirmation.

GET /public/clinics/:slug

Retrieve public-facing information about a clinic by its URL slug. Path parameters

slug

string

required

The clinic’s URL-safe slug (e.g., clinica-san-rafael).

Response — PublicClinic

string

UUID of the clinic. Use this as clinic_id in subsequent booking requests.

name

string

Clinic display name.

slug

string

URL-safe slug.

clinic_type

string

Clinic type (e.g., general, dental, obstetrics).

specialty_modules

string[]

Active specialty modules for this clinic.

phone

string | null

Administrative phone number.

string | null

Administrative email.

public_phone

string | null

Public-facing phone number shown to patients.

public_email

string | null

Public-facing email shown to patients.

address

string | null

Physical address.

timezone

string

IANA timezone identifier (e.g., America/Costa_Rica).

logo_path

string | null

URL or path to the clinic’s logo image.

theme_color

string | null

Hex color used to brand the booking widget.

booking_enabled

boolean

Whether online booking is currently enabled. If false, do not show the booking flow.

curl --request GET \
  --url http://localhost:3001/public/clinics/clinica-san-rafael

{
  "id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "name": "Clínica San Rafael",
  "slug": "clinica-san-rafael",
  "clinic_type": "general",
  "specialty_modules": ["general"],
  "phone": null,
  "email": null,
  "public_phone": "+50622334455",
  "public_email": "citas@clinicasanrafael.cr",
  "address": "100m norte del parque, San José",
  "timezone": "America/Costa_Rica",
  "logo_path": "/logos/clinica-san-rafael.png",
  "theme_color": "#2563EB",
  "booking_enabled": true
}

GET /booking/services

List active services offered by a clinic. Query parameters

clinic_id

string

required

UUID of the clinic (obtained from GET /public/clinics/:slug).

doctor_id

string

Filter services to those offered by a specific doctor UUID.

Response — ServiceSummary[]

string

UUID of the service.

name

string

Service name (e.g., “Consulta General”).

description

string | null

Optional service description.

duration_minutes

number

Duration of the service in minutes.

price

number

Price in cents (CRC colones).

curl --request GET \
  --url "http://localhost:3001/booking/services?clinic_id=7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

GET /booking/doctors

List doctors at a clinic who provide a specific service. Query parameters

clinic_id

string

required

UUID of the clinic.

service_id

string

Filter doctors to those who offer a specific service UUID.

Response — DoctorSummary[]

string

UUID of the doctor.

first_name

string

Doctor’s first name.

last_name

string

Doctor’s last name.

specialty

string | null

Doctor’s medical specialty, or null.

curl --request GET \
  --url "http://localhost:3001/booking/doctors?clinic_id=7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&service_id=svc_789"

GET /booking/available-slots

Retrieve available appointment slots for a clinic, date, and service. Query parameters

clinic_id

string

required

UUID of the clinic.

date

string

required

Date to check in YYYY-MM-DD format.

doctor_id

string

UUID of a specific doctor. When omitted (or any), the backend merges available slots across all doctors for the service and attaches a real doctor_id to each slot.

service_id

string

UUID of the service being booked. Used to filter eligible doctors and calculate slot duration.

Response — AvailableSlotsResponse

date

string

The queried date (YYYY-MM-DD).

doctor_id

string

The doctor UUID used for the query. May differ from the input when any was passed.

slots

TimeSlot[]

List of time slots for the day.

Show TimeSlot properties

time

string

Slot start time in HH:mm format (24-hour, Costa Rica local time).

available

boolean

Whether the slot is open for booking.

doctor_id

string | null

Doctor UUID assigned to this slot. Populated when the request used any as the doctor.

curl --request GET \
  --url "http://localhost:3001/booking/available-slots?clinic_id=7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&date=2026-05-20&service_id=svc_789"

{
  "date": "2026-05-20",
  "doctor_id": "d_def456",
  "slots": [
    { "time": "08:00", "available": true, "doctor_id": "d_def456" },
    { "time": "08:30", "available": false, "doctor_id": null },
    { "time": "09:00", "available": true, "doctor_id": "d_def456" }
  ]
}

POST /booking/appointments

Submit a booking. Creates a new appointment and returns a confirmation. Patient identity is matched by identification; if no patient record exists with that ID, a new patient record is created automatically. Request body

service_id

string

required

UUID of the service being booked.

doctor_id

string

required

UUID of the doctor. Use the doctor_id from the chosen slot in the available-slots response.

date

string

required

Appointment date in YYYY-MM-DD format.

time

string

required

Appointment start time in HH:mm format (24-hour).

first_name

string

required

Patient’s first name.

last_name

string

required

Patient’s last name.

identification

string

required

Patient’s national ID number (cédula).

clinic_id

string

UUID of the clinic. Either clinic_id or clinic_slug must be provided.

clinic_slug

string

URL-safe clinic slug. Either clinic_id or clinic_slug must be provided.

whatsapp_phone

string

Patient’s WhatsApp number for appointment reminders.

Response — BookingConfirmation

string

UUID of the newly created appointment.

status

string

Initial appointment status (typically PENDING).

start_time

string

ISO 8601 UTC start time of the appointment.

end_time

string

ISO 8601 UTC end time of the appointment.

reason

string | null

Booking reason, or null.

service

object | null

Show Service summary

name

string

Name of the booked service.

doctor

object

Show Doctor summary

first_name

string

Doctor’s first name.

last_name

string

Doctor’s last name.

curl --request POST \
  --url http://localhost:3001/booking/appointments \
  --header "Content-Type: application/json" \
  --data '{
    "clinic_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "service_id": "svc_789",
    "doctor_id": "d_def456",
    "date": "2026-05-20",
    "time": "09:00",
    "first_name": "Carlos",
    "last_name": "Mora",
    "identification": "209876543",
    "whatsapp_phone": "+50688001122"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "start_time": "2026-05-20T15:00:00Z",
  "end_time": "2026-05-20T15:30:00Z",
  "reason": null,
  "service": { "name": "Consulta General" },
  "doctor": { "first_name": "Ana", "last_name": "Rodríguez" }
}

Overview

Endpoints

Public booking API endpoints

Booking flow

GET /public/clinics/:slug

GET /booking/services

GET /booking/doctors

GET /booking/available-slots

POST /booking/appointments

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Booking flow

​GET /public/clinics/:slug

​GET /booking/services

​GET /booking/doctors

​GET /booking/available-slots

​POST /booking/appointments

Build docs developers (and LLMs) love

Booking flow

GET /public/clinics/:slug

GET /booking/services

GET /booking/doctors

GET /booking/available-slots

POST /booking/appointments