# Booking reference

> Online booking for practices that run their diary in Orkero.

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

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`](#listbookingvisits) | List the visits a practice offers online | `booking.read` |
| [`GET /v1/booking/times`](#listbookingtimes) | List free times for a visit | `booking.read` |
| [`GET /v1/booking/bookings`](#getbookings) | Look up the key's bookings | `booking.write` |
| [`POST /v1/booking/bookings`](#createbooking) | Book an appointment | `booking.write` |
| [`POST /v1/booking/bookings/change`](#changebooking) | Move a booking to another time | `booking.write` |
| [`POST /v1/booking/bookings/cancel`](#cancelbooking) | 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

```bash
curl "https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"
```
```typescript
const res = await fetch("https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
  },
});
const answer = await res.json();
```
```python
import os, requests

res = requests.get(
    "https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
```

### Answer (200)

```json
{
  "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

```bash
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"
```
```typescript
const res = await fetch("https://api.orkero.app/v1/booking/times?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99&visit_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
  },
});
const answer = await res.json();
```
```python
import os, requests

res = requests.get(
    "https://api.orkero.app/v1/booking/times?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99&visit_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
```

### Answer (200)

```json
{
  "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

```bash
curl "https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"
```
```typescript
const res = await fetch("https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
  },
});
const answer = await res.json();
```
```python
import os, requests

res = requests.get(
    "https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
```

### Answer (200)

```json
{
  "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

```bash
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"}}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/booking/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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"
    }
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/booking/bookings",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "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 = res.json()
```

### Answer (200)

```json
{
  "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

```bash
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>"}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/booking/bookings/change", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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>"
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/booking/bookings/change",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "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 = res.json()
```

### Answer (200)

```json
{
  "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

```bash
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"}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/booking/bookings/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99"
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/booking/bookings/cancel",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
        "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99"
    },
)
answer = res.json()
```

### Answer (200)

```json
{
  "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`. |
