Booking

External booking is a two-step conversation with the diary: ask what is free, then book one of the answers. Both steps run on the same engine as the PracticeHub calendar and online booking, so a slot the API offers is a slot the practice would book.

Find free slots

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/availability?location_id=81&appointment_type_id=1&from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $KEY"

{
  "data": [
    {
      "starts_at": "2026-09-01T09:00:00",
      "ends_at": "2026-09-01T09:30:00",
      "practitioner_id": 109,
      "practitioner_name": "Ada Lovelace",
      "location_id": 81,
      "appointment_type_id": 1,
      "resource_id": null,
      "type": "individual",
      "group_master_id": null,
      "online_fee": 45
    }
  ],
  "meta": {
    "timezone": "Europe/London",
    "from": "2026-09-01T00:00:00",
    "to": "2026-09-07T23:59:59",
    "visibility": "online",
    "unavailable_dates": ["2026-09-06"]
  }
}

Slots are in the clinic timezone, earliest first, at most 50 per day. unavailable_dates lists days in the range with nothing free — handy for greying out a calendar without a request per day.

Book one of them

curl -X POST https://your-clinic.your-region.practicehub.io/v3/api/appointments \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-7f3a" \
  -d '{
    "patient_id": 340, "location_id": 81, "appointment_type_id": 1, "practitioner_id": 109,
    "starts_at": "2026-09-01T09:00:00", "ends_at": "2026-09-01T09:30:00"
  }'

Copy starts_at, ends_at, practitioner_id, location_id and appointment_type_id straight from the slot — and resource_id too when the slot carries one (resource-view locations, calendar_view = 1 on GET /locations, need it; practitioner-view locations return null and need none). For a group slot send its group_master_id instead of starts_at/ends_at — you are taking a place in an existing session.

Know what booking does — and doesn't — check

POST /appointments does not look at the practitioner’s diary. Like a staff member clicking a time in the PracticeHub calendar, it books what you send: the patient, location, practitioner, type and resource are validated, but a time that is already taken is written alongside the existing appointment, not refused. Someone may book the same time between your two calls; if that matters to you, re-check availability just before you post (or reconcile afterwards). The one capacity rule that is enforced is a group session’s size — 409 group_full when it is full. The Idempotency-Key makes a retry of the same booking safe, but a new time is a new request.

Parameters

Parameter	Required	Meaning
`location_id`	Yes	Location to search
`appointment_type_id`	Yes	Appointment type to book
`practitioner_id`	No	Limit to one practitioner; omit for any practitioner who provides the type
`from`	No	Range start, `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS` in the clinic timezone. Default: start of today
`to`	No	Range end (inclusive; a date means the end of that day). Default: 7 days from `from`; at most 31 days — page by week or month for wider views
`visibility`	No	`online` (default) or `all` — see below
`max_per_day`	No	Cap on slots per day (1–50)
`rescheduled_appointment_id`	No	When finding a new time for an existing appointment: the time it occupies is treated as free for overlapping alternatives (and its own duration/columns are used), but its exact current start is not offered — that would not be a move

Two views of the diary

visibility=online (default)

What a patient sees when booking online. The location, appointment type and (if given) practitioner must be enabled for online booking — otherwise 422 not_online_bookable — and every online-booking rule applies: minimum advance notice, how far ahead, daily caps, online-only availability guides, slot clustering. Use this for websites, apps and marketplaces.

visibility=all

What the front desk could book: every open slot for practitioners who provide the type, subject only to physical capacity (columns / resources). No online-booking rules. Use this for staff-facing tools and internal automations.

Booking is what the calendar allows staff

GET /availability is how you look before you leap; POST /appointments books what you send, exactly as a staff member clicking the calendar would — it does not check whether the practitioner is free at that time, and there is no locking between two callers. That is deliberate: a data migration or a practice that double-books on purpose needs to be able to write wherever it says. For a public flow, always book a slot /availability returned, and re-query if any time has passed since you fetched it.

Not the same as `practitioner_availabilities`

practitioner_availabilities is a resource: the raw working-hours records (who is in, where, when). GET /availability is a computation over those records, existing appointments, closures, resources and the appointment type — the free time that is left. Read the first to know when someone works; call the second to know when they can be booked.

Rate limits are per account (120 requests a minute across all of its API keys). A booking widget serving many visitors should fetch a week at a time and re-check only when the visitor picks a day, rather than polling per day.

Getting started

Concepts

Working with the API

Ship it

Resource guides

Importing your data

Parameters

Two views of the diary

visibility=online (default)

visibility=all

Booking is what the calendar allows staff

Not the same as `practitioner_availabilities`

​Parameters

​Two views of the diary

visibility=online (default)

visibility=all

​Booking is what the calendar allows staff

​Not the same as practitioner_availabilities

Parameters

Two views of the diary

Booking is what the calendar allows staff

Not the same as `practitioner_availabilities`