Docs
View as Markdown

Booking reference

Online booking for practices that run their diary in Orkero.

Online booking for practices that run their diary in Orkero. The rules are the practice's own booking page's, with the key in place of the human check. A key reads back, changes and cancels only the bookings it made.

Request What it does Scope
GET /v1/booking/visits List the visits a practice offers online booking.read
GET /v1/booking/times List free times for a visit booking.read
GET /v1/booking/bookings Look up the key's bookings booking.write
POST /v1/booking/bookings Book an appointment booking.write
POST /v1/booking/bookings/change Move a booking to another time booking.write
POST /v1/booking/bookings/cancel Cancel a booking booking.write

List the visits a practice offers online

GET /v1/booking/visits

Scope: booking.read.

Query

Name Type Needed What it is
practice_id string (uuid) yes

Example

curl "https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"

Answer (200)

{
  "ok": true,
  "practice": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "name": "<name>",
    "address": [
      "<address>"
    ],
    "postcode": "<postcode>",
    "phone": "<phone>",
    "email": "<email>",
    "time_zone": "<time_zone>",
    "privacy_url": "<privacy_url>"
  },
  "currency": "GBP",
  "first_day": "2026-11-24",
  "last_day": "2026-11-24",
  "visits": [
    {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "name": "<name>",
      "description": "<description>",
      "minutes": 1,
      "category": "<category>",
      "fee_pence": 9900,
      "nhs_fee_pence": 9900,
      "care_plan_fee_pence": 9900
    }
  ],
  "request_id": "web-000123"
}

Errors

Status When
401 no_such_key, key_switched_off, key_ended.
403 not_allowed (the key lacks the scope), not_your_practice, whole_organisation.
409 booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off.
422 A field is wrong; the message says which and why. refused carries words for the person booking.
429 too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy.

List free times for a visit

GET /v1/booking/times

Times that fit the practice's diary well, exactly as its booking page offers them. A time reserves nothing: ask again just before showing it. Two weeks a request at most; covered_to is the last day searched in full.

Scope: booking.read.

Query

Name Type Needed What it is
practice_id string (uuid) yes
visit_id string (uuid) yes
from string (date)
to string (date)

Example

curl "https://api.orkero.app/v1/booking/times?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99&visit_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"

Answer (200)

{
  "ok": true,
  "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
  "visit_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
  "time_zone": "<time_zone>",
  "from": "2026-11-24",
  "covered_to": "2026-11-24",
  "first_day": "2026-11-24",
  "last_day": "2026-11-24",
  "times": [
    {
      "starts_at": "2026-11-24T09:00:00+00:00",
      "ends_at": "2026-11-24T09:00:00+00:00",
      "clinician": "<clinician>",
      "name": "<name>",
      "role": "<role>"
    }
  ],
  "request_id": "web-000123"
}

Errors

Status When
401 no_such_key, key_switched_off, key_ended.
403 not_allowed (the key lacks the scope), not_your_practice, whole_organisation.
404 no_such_visit, no_such_booking, no_such_line.
409 booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off.
422 A field is wrong; the message says which and why. refused carries words for the person booking.
429 too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy.

Look up the key's bookings

GET /v1/booking/bookings

With id: that booking, whatever has become of it. Without: the key's bookings still to come at the practice, soonest first (200 at most). A booking the key did not make is 404 no_such_booking.

Scope: booking.write.

Query

Name Type Needed What it is
practice_id string (uuid) yes
id string (uuid)

Example

curl "https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"

Answer (200)

{
  "ok": true,
  "booking": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "state": "booked",
    "first_name": "Jane",
    "visit": {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "name": "<name>",
      "category": "<category>"
    },
    "starts_at": "2026-11-24T09:00:00+00:00",
    "ends_at": "2026-11-24T09:00:00+00:00",
    "clinician": {
      "key": "<key>",
      "name": "<name>",
      "role": "<role>"
    },
    "funding": "private",
    "can_change": true,
    "change_until": "2026-11-24T09:00:00+00:00"
  },
  "bookings": [
    {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "state": "booked",
      "first_name": "Jane",
      "visit": {},
      "starts_at": "2026-11-24T09:00:00+00:00",
      "ends_at": "2026-11-24T09:00:00+00:00",
      "clinician": {},
      "funding": "private",
      "can_change": true,
      "change_until": "2026-11-24T09:00:00+00:00"
    }
  ],
  "request_id": "web-000123"
}

Errors

Status When
401 no_such_key, key_switched_off, key_ended.
403 not_allowed (the key lacks the scope), not_your_practice, whole_organisation.
404 no_such_visit, no_such_booking, no_such_line.
429 too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy.

Book an appointment

POST /v1/booking/bookings

Books a time /v1/booking/times offers at that moment. The practice finds its patient on an exact match or adds one. Sending the same request_id again books once (200, duplicate: true). With a test key the booking is checked all the way through and undone (200, test: true, no id).

Scope: booking.write.

Body

Field Type Needed What it is
practice_id string (uuid) yes
request_id string yes Your own name for this request. Send it again unchanged when unsure; it is booked once. 8 to 100 characters.
visit_id string (uuid) yes
starts_at string (date‑time) yes
clinician string yes
funding string One of private, nhs, care_plan. Default private.
person object yes At least one of mobile, phone and email.
person.first_name string yes
person.last_name string yes
person.date_of_birth string (date) yes
person.mobile string International form, e.g. +447700900123.
person.phone string
person.email string (email)
been_before string One of yes, no, not_sure. Default not_sure.
note string 0 to 400 characters.

Example

curl -X POST "https://api.orkero.app/v1/booking/bookings" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","request_id":"web-000123","visit_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","starts_at":"2026-11-24T09:00:00+00:00","clinician":"<clinician>","person":{"first_name":"Jane","last_name":"Smith","date_of_birth":"2026-11-24","mobile":"<mobile>","phone":"<phone>","email":"jane@example.org"}}'

Answer (200)

{
  "ok": true,
  "emailed": true,
  "duplicate": true,
  "test": true,
  "booking": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "state": "booked",
    "first_name": "Jane",
    "visit": {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "name": "<name>",
      "category": "<category>"
    },
    "starts_at": "2026-11-24T09:00:00+00:00",
    "ends_at": "2026-11-24T09:00:00+00:00",
    "clinician": {
      "key": "<key>",
      "name": "<name>",
      "role": "<role>"
    },
    "funding": "private",
    "can_change": true,
    "change_until": "2026-11-24T09:00:00+00:00"
  },
  "request_id": "web-000123"
}

Errors

Status When
401 no_such_key, key_switched_off, key_ended.
403 not_allowed (the key lacks the scope), not_your_practice, whole_organisation.
409 booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off.
422 A field is wrong; the message says which and why. refused carries words for the person booking.
429 too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy.

Move a booking to another time

POST /v1/booking/bookings/change

Open until 24 hours before the appointment (409 too_late after). Add visit_id or funding to change those too. The patient's earlier "Manage my booking" link is replaced by the one in the new email.

Scope: booking.write.

Body

Field Type Needed What it is
practice_id string (uuid) yes
id string (uuid) yes
request_id string yes 8 to 100 characters.
starts_at string (date‑time) yes
clinician string yes
visit_id string (uuid)
funding string One of private, nhs, care_plan. Default private.

Example

curl -X POST "https://api.orkero.app/v1/booking/bookings/change" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","request_id":"web-000123","starts_at":"2026-11-24T09:00:00+00:00","clinician":"<clinician>"}'

Answer (200)

{
  "ok": true,
  "emailed": true,
  "duplicate": true,
  "test": true,
  "booking": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "state": "booked",
    "first_name": "Jane",
    "visit": {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "name": "<name>",
      "category": "<category>"
    },
    "starts_at": "2026-11-24T09:00:00+00:00",
    "ends_at": "2026-11-24T09:00:00+00:00",
    "clinician": {
      "key": "<key>",
      "name": "<name>",
      "role": "<role>"
    },
    "funding": "private",
    "can_change": true,
    "change_until": "2026-11-24T09:00:00+00:00"
  },
  "request_id": "web-000123"
}

Errors

Status When
401 no_such_key, key_switched_off, key_ended.
403 not_allowed (the key lacks the scope), not_your_practice, whole_organisation.
404 no_such_visit, no_such_booking, no_such_line.
409 booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off.
422 A field is wrong; the message says which and why. refused carries words for the person booking.
429 too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy.

Cancel a booking

POST /v1/booking/bookings/cancel

Open until 24 hours before. Asked again it answers the same, with duplicate.

Scope: booking.write.

Body

Field Type Needed What it is
practice_id string (uuid) yes
id string (uuid) yes

Example

curl -X POST "https://api.orkero.app/v1/booking/bookings/cancel" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99"}'

Answer (200)

{
  "ok": true,
  "emailed": true,
  "duplicate": true,
  "test": true,
  "booking": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "state": "booked",
    "first_name": "Jane",
    "visit": {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "name": "<name>",
      "category": "<category>"
    },
    "starts_at": "2026-11-24T09:00:00+00:00",
    "ends_at": "2026-11-24T09:00:00+00:00",
    "clinician": {
      "key": "<key>",
      "name": "<name>",
      "role": "<role>"
    },
    "funding": "private",
    "can_change": true,
    "change_until": "2026-11-24T09:00:00+00:00"
  },
  "request_id": "web-000123"
}

Errors

Status When
401 no_such_key, key_switched_off, key_ended.
403 not_allowed (the key lacks the scope), not_your_practice, whole_organisation.
404 no_such_visit, no_such_booking, no_such_line.
409 booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off.
429 too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy.