# Booking quickstart

> Show a practice's free times and book a patient in, in five minutes.

Source: https://docs.orkero.app/quickstart/booking

For a website, an app or a phone assistant that books into a practice's own diary. You can
only ever book a time the practice's own booking page would offer, so you never double-book
a clinician or use a slot the practice keeps back.

You need a key with `booking.read` and `booking.write`, and the practice's id.

## 1. See what the practice offers

```bash
curl "https://api.orkero.app/v1/booking/visits?practice_id=$PRACTICE" \
  -H "Authorization: Bearer $ORKERO_KEY"
```

```json
{"ok": true,
 "practice": {"id": "…", "name": "Demo Opticians", "time_zone": "Europe/London"},
 "currency": "GBP", "first_day": "2026-11-23", "last_day": "2027-02-12",
 "visits": [{"id": "…", "name": "Adult Comprehensive Eye Examination",
             "minutes": 40, "fee_pence": 9900, "nhs_fee_pence": 0}]}
```

Prices are whole pence. `nhs_fee_pence` of `null` means the visit is not offered on the NHS.

## 2. Find a free time

```bash
curl "https://api.orkero.app/v1/booking/times?practice_id=$PRACTICE&visit_id=$VISIT" \
  -H "Authorization: Bearer $ORKERO_KEY"
```

Each time has `starts_at`, `ends_at`, and `clinician` (an opaque key for the person, with
their first name and role). A time reserves nothing: ask again just before you show it, and
show it in the practice's `time_zone`. Two weeks a request at most; `covered_to` is the last
day searched.

## 3. Book

```bash
curl https://api.orkero.app/v1/booking/bookings \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "practice_id": "'$PRACTICE'",
    "request_id": "web-000123",
    "visit_id": "'$VISIT'",
    "starts_at": "2026-11-24T09:00:00+00:00",
    "clinician": "3f9a1c…",
    "person": {"first_name": "Jane", "last_name": "Smith",
               "date_of_birth": "1980-02-03", "email": "jane@example.org"}
  }'
```

`201` means booked. Keep `booking.id`. The practice finds its existing patient on an exact
match, or adds a new one, and emails the patient their confirmation with a private "Manage
my booking" link (`"emailed": true`).

If the time went a moment before, you get `409 time_gone`: ask for the times again. With a
test key the booking is checked all the way through and undone, so nothing is booked.

## 4. Move or cancel

```bash
curl https://api.orkero.app/v1/booking/bookings/cancel \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"practice_id": "'$PRACTICE'", "id": "'$BOOKING'"}'
```

Both are open until 24 hours before the appointment (`409 too_late` after). Your key only
ever sees, moves and cancels the bookings it made.

## 5. Hear about changes

A patient can move or cancel through their email link, and the practice can change a
booking at the desk. Add a [webhook](/webhooks) for `booking.booked`, `booking.changed` and
`booking.cancelled`: `data.by` says who did it (`api`, `patient` or `practice`).

Full detail: [Booking reference](/reference/booking).
