# Public booking API

> Every endpoint of the public booking API, with its parameters, answers and errors, and how access from browsers, rate limits, caching and paused locations work.

Source: https://docs.bifrostorbit.com/booking/developers/public-api/

The public booking API is what the booking page, the widget and the [Booking SDK](https://docs.bifrostorbit.com/booking/developers/booking-sdk/) use. It is plain JSON over HTTPS, so you can call it from any language.

The [public booking API reference](https://docs.bifrostorbit.com/reference/booking-public/) lists every endpoint with its fields, code samples in six languages and a console that runs the reads from your browser. It is built from the [OpenAPI 3.1 document](https://docs.bifrostorbit.com/reference/booking-public/openapi.json), which you can load into Postman, Insomnia or a client generator.

```text
https://app.bifrostorbit.com/booking/api/public/<location>
```

`<location>` is the location's short name, such as `northwilds-oslo`, the last part of its booking page address. On staging, use `https://stage.bifrostorbit.com/booking/api/public/<location>`.

## How it works

- **No key:** The API needs no key or token. Changing an appointment needs its manage token, which only the customer gets.
- **Answers** come as `{ "data": … }` with status `200`, or `201` when something was created.
- **Errors** come as `{ "error": { "code": "…", "message": "…" } }`. The message is in English and fine to show to a customer. Wrong or missing fields answer `422` with `issues`, the list of fields that failed, each with its `path` and a `message` in English.
- **Times** are ISO 8601. Booking Orbit answers in UTC, such as `2026-11-12T09:45:00.000Z`, and takes any time with a zone or offset. Days are `YYYY-MM-DD`.
- **Money** is in the currency's smallest unit: `45000` with `NOK` is NOK 450.
- **Ids or short names:** Wherever a service is asked for, you can send its `id` or its `slug`, such as `boot-fitting`.
- **Language:** `locale` picks the language of texts such as the intro, form questions and the emails to the customer, from the languages the location offers. Other values fall back to the location's default language.

## Access from browsers

| Endpoints | From your server | From a browser |
| --- | --- | --- |
| Reading: the location, services, people and free times | Yes | From any website |
| Changing: holds, bookings, the waitlist, and reading or changing one appointment | Yes | Only from the location's allowed websites |

A browser sends an `Origin` header; a server doesn't. Booking Orbit answers browsers from an allowed website with that origin in `Access-Control-Allow-Origin`, and other websites with `*` for reading only. A change from any other website answers `403`, and the browser shows a CORS error for its preflight. Add your website under **Settings › Your website**: see [Allowed websites](https://docs.bifrostorbit.com/booking/developers/allowed-websites/).

## Rate limits

Each visitor's IP address may make, per location:

| Endpoints | Per minute | In a burst |
| --- | --- | --- |
| Reading: `GET /`, `/services`, `/services/<service>`, `/staff`, `/slots` | 120 | 120 |
| Holding: `POST /holds`, `DELETE /holds/<token>` | 10 | 20 |
| Booking: `POST /appointments` and `POST /waitlist` together | 5 | 10 |
| One appointment: everything under `/manage/<token>`, and `GET /offers/<token>` | 10 | 20 |

Over the limit, the answer is `429` with the code `rate_limited`. Wait a minute and try again.

Calls from your server all come from your server's address, so they share one allowance. Read on the server and cache the answers, and let visitors' browsers hold and book, so each visitor has their own allowance.

## Caching

Reading answers for the location, services and people may be cached for 60 seconds (`Cache-Control: public, max-age=60, stale-while-revalidate=240`). Free times may be cached by the browser for 15 seconds. Everything else is never cached.

## Paused locations

When an organisation's Booking Orbit trial or plan has ended, changes answer `402` with the code `subscription_inactive`. Reading still works, so show the services with a note that online booking is unavailable for now. Nothing is deleted, and booking works again as soon as an owner chooses a plan.

## The location

```http
GET /
```

| Parameter | |
| --- | --- |
| `locale` | Optional. The language of `intro`. |

Answers with the location: `id`, `slug`, `name`, `description`, `intro`, `kind` (`place` or `online`), `address` (`lines`, `city`, `region`, `postcode`, `country`, or `null` for an online location), `timeZone`, `currency`, `locales`, `defaultLocale`, `logoUrl`, `coverUrl`, `colour`, `phone`, `email` and `openingHours`, one entry per open day, `day` 0 for Sunday to 6 for Saturday, with its `ranges` such as `{ "from": "08:00", "to": "20:00" }`.

It also says how to build the booking form:

| Field | What it says |
| --- | --- |
| `policies.cancelUntilHours` | Customers may cancel online until this many hours before |
| `policies.rescheduleUntilHours` | Customers may move online until this many hours before |
| `policies.requireApproval` | New bookings wait for the team to confirm them |
| `bookingPage.showStaff` | Customers may choose a person. If `false`, `/staff` is empty. |
| `bookingPage.showPrices` | Prices are shown. If `false`, every service's price is `{ "kind": "hidden", "amount": null }`. |
| `bookingPage.phone`, `bookingPage.notes` | `required`, `optional` or `hidden` |
| `bookingPage.waitlist` | Customers may join the waitlist |
| `bookingPage.marketing` | Ask whether the customer wants news. Send their answer as `marketing`. |
| `bookingPage.termsUrl`, `bookingPage.privacyUrl` | Link to these beside the **Book** button |

## Services

```http
GET /services
```

Answers `{ "services": [...] }`, the services listed on the booking page, in their order. Each service has:

| Field | |
| --- | --- |
| `id`, `slug`, `name`, `description`, `category`, `imageUrl` | |
| `durationMinutes` | |
| `mode` | `in-person`, `online` or `either` |
| `price` | `kind`: `free`, `fixed`, `from` or `hidden`, and `amount` |
| `payment` | `rule`: `none`, `deposit` or `full`, and `depositAmount`. A service with a deposit or the full price paid online can't be booked through the API: see **Services paid online** below. |
| `capacity` | Places in one session. Above 1, several customers book the same time. |
| `staffIds` | The people who take it. Empty means anyone. |
| `formId` | The intake form, or `null` |

Services shown only **With a link** are left out, but you can read and book them by id or short name.

```http
GET /services/<service>
```

| Parameter | |
| --- | --- |
| `locale` | Optional. The language of the form. |

Answers `{ "service", "staff", "form" }`: the service, the people who take it, and the questions to ask. Each question has `id`, `type`, `label`, `help`, `required` and `options` (`id` and `label`). Types are `short-text`, `long-text`, `number`, `choice`, `choices`, `yes-no`, `date` and `consent`. File questions are only on the booking page.

## People

```http
GET /staff?service=<service>
```

Answers `{ "staff": [...] }` with `id`, `name`, `title`, `bio` and `photoUrl` for each bookable person, only those who take the service when you name one. Empty when the location doesn't let customers choose a person.

## Free times

```http
GET /slots?service=<service>
```

| Parameter | |
| --- | --- |
| `service` | Required |
| `staff` | Optional. A person's id, to show only their times. |
| `from` | Optional. The first day, `YYYY-MM-DD`. Today if left out or in the past. |
| `days` | Optional. How many days, 1 to 42. 14 if left out. |
| `timeZone` | Optional. An IANA time zone such as `Europe/Oslo`, so days start and end at the customer's midnight. The location's own if left out. |
| `manage` | Optional. The manage token of an appointment being moved, so its own time counts as free. |

```json
{
  "data": {
    "timeZone": "Europe/Oslo",
    "from": "2026-11-09",
    "to": "2026-11-12",
    "days": [
      {
        "date": "2026-11-09",
        "slots": [
          { "startsAt": "2026-11-09T09:00:00.000Z", "endsAt": "2026-11-09T09:45:00.000Z", "staffIds": ["…"], "placesLeft": null }
        ]
      }
    ],
    "next": { "startsAt": "2026-11-09T09:00:00.000Z", "staffIds": ["…"] },
    "maxDays": 42
  }
}
```

`to` is the day after the last one. Every day is listed, with an empty `slots` when nothing is free. `staffIds` are the people free at that time. `placesLeft` counts free places for services with more than one place, and is `null` otherwise. `next` is the first free time, looked for beyond your days too, up to as far ahead as the location takes bookings, or `null`. Times already follow the location's rules: opening hours, notice, how far ahead, breaks and calendars.

## Holds

```http
POST /holds
```

```json
{ "service": "boot-fitting", "staff": null, "startsAt": "2026-11-12T09:45:00.000Z" }
```

Holds the time for 10 minutes, so nobody else can take it while the customer fills in the form. `staff` is optional: without it, Booking Orbit picks a free person. Answers `201` with `token`, `expiresAt`, and the `staffId` and `staffName` it picked. If the time has just gone, the answer is `409`. A service paid online when booked answers `409` with the code `payment_required`, as booking does.

```http
DELETE /holds/<token>
```

Lets the time go, for example when the customer goes back. Answers `{ "released": true }`, also for a hold that had already run out.

## Booking

```http
POST /appointments
```

| Field | |
| --- | --- |
| `service` | Required |
| `startsAt` | Required |
| `holdToken` | Recommended. The hold's token. Booking fails with `409` if the hold has run out or is for another time. |
| `staff` | Optional. Without a hold or a person, Booking Orbit picks one. |
| `name` | Required, up to 120 characters |
| `email` | Required. The confirmation and reminders go here. |
| `phone` | Required when `bookingPage.phone` is `required`, ignored when it's `hidden` |
| `notes` | Optional, up to 2,000 characters. Ignored when `bookingPage.notes` is `hidden`. |
| `answers` | The form's answers, keyed by question `id`. Send option ids for `choice` (one) and `choices` (a list), `true` or `false` for `yes-no` and `consent`, and `YYYY-MM-DD` for `date`. |
| `marketing` | Optional. `true` if the customer wants news, when `bookingPage.marketing` is on. |
| `locale` | Optional. The customer's language, for their emails. |
| `timeZone` | Optional. The customer's time zone, for their emails. |

Answers `201` with `appointment` and `payment`:

```json
{
  "data": {
    "appointment": {
      "reference": "29BMJM",
      "status": "confirmed",
      "service": { "id": "…", "slug": "boot-fitting", "name": "Boot fitting", "durationMinutes": 45, "mode": "in-person" },
      "staff": "Ingrid Berg",
      "startsAt": "2026-11-12T09:45:00.000Z",
      "endsAt": "2026-11-12T10:30:00.000Z",
      "timeZone": "Europe/Oslo",
      "attendee": { "name": "Ingrid Berg", "email": "ingrid@northwilds.com" },
      "manageUrl": "https://app.bifrostorbit.com/booking/m/…",
      "calendar": { "ics": "/booking/api/public/northwilds-oslo/manage/…/calendar", "google": "https://calendar.google.com/…", "outlook": "https://outlook.live.com/…" },
      "canChange": true,
      "changeUntil": "2026-11-11T09:45:00.000Z",
      "cancelReason": null,
      "meetingUrl": null,
      "location": { "name": "Northwilds Oslo", "slug": "northwilds-oslo", "address": "Karl Johans gate 12, 0154 Oslo, NO", "online": false, "phone": "+47 22 00 00 00", "email": "oslo@northwilds.com" }
    },
    "payment": { "required": false, "method": "at-location", "rule": null, "amount": 45000, "currency": "NOK", "manageToken": null, "url": null }
  }
}
```

- `status` is `confirmed`, or `pending` when the location confirms bookings itself.
- `manageUrl` is the customer's own page for the appointment, also in their email. Its last part is the **manage token**: keep it safe, since anyone with it can move or cancel the appointment.
- `calendar.ics` is a path on the Booking Orbit address. `google` and `outlook` add the appointment to those calendars.
- `meetingUrl` is the video link for online appointments, once there is one.
- `payment.method` is `none`, `at-location` (paid at the location) or `online`.

The same person can book a limited number of times a day when the location sets a limit; one more answers `409`.

## Services paid online

Only the booking page and the [widget](https://docs.bifrostorbit.com/booking/developers/embed-the-widget/) take payments, with Stripe. So when the location takes payments online and a service asks for a deposit, the full price or a saved card when it's booked, `POST /holds` and `POST /appointments` refuse it from your website or server, and nothing is held or booked:

```json
{
  "error": {
    "code": "payment_required",
    "message": "This service is paid online when it's booked, so book it on the booking page.",
    "rule": "deposit",
    "bookingUrl": "https://app.bifrostorbit.com/booking/b/northwilds-oslo?service=boot-fitting&start=2026-11-12T09%3A45%3A00.000Z"
  }
}
```

The status is `409`. `rule` is `deposit`, `full` or `card-on-file`. `bookingUrl` opens the service on the location's booking page, with the person and time you sent already chosen, and the customer's language when it isn't the location's main one. Send the customer there, or open the widget, to book and pay.

Services paid at the location, and free services, book through the API as above. The booking page and the widget call the same API and get `payment.required: true` with the payment step instead.

## One appointment

Every call here takes the manage token from `manageUrl`.

```http
GET /manage/<token>?locale=<locale>
```

Answers `{ "appointment": … }`, as booking does. `canChange` says whether the customer may still move or cancel it online, and `changeUntil` until when. `status` is one of `pending`, `confirmed`, `checked-in`, `completed`, `cancelled` and `no-show`.

```http
POST /manage/<token>/reschedule
```

```json
{ "startsAt": "2026-11-12T10:00:00.000Z", "staff": null, "locale": "en" }
```

Moves it and answers `{ "appointment": … }`. Use `GET /slots?manage=<token>` to find times, so the appointment's own time shows as free. Without `staff`, it stays with the same person if they are free, or goes to another. Too close to the start answers `403`.

```http
POST /manage/<token>/cancel
```

```json
{ "reason": "Ill", "locale": "en" }
```

Cancels it and answers `{ "appointment": … }`. `reason` is optional, up to 500 characters. Too close to the start answers `403`; an appointment that is over or already cancelled answers `409`.

```http
GET /manage/<token>/calendar
```

Answers the appointment as a calendar file, `text/calendar`, named after its reference, such as `29BMJM.ics`.

## Waitlist

```http
POST /waitlist
```

```json
{ "service": "climbing-lesson", "staff": null, "from": "2026-11-10", "to": "2026-11-20", "name": "Ingrid Berg", "email": "ingrid@northwilds.com", "phone": null, "locale": "en", "timeZone": "Europe/Oslo" }
```

`timeZone` is optional: the customer's IANA time zone, for their emails, as when booking. The days themselves always count in the location's time zone.

Puts the customer on the waitlist for those days, up to 90, and answers `201` with `{ "joined": true }`. Joining again for the same service replaces the days. When a time frees up, Booking Orbit offers it to the customer by email with a link to the booking page. `403` means the location doesn't keep a waitlist (`bookingPage.waitlist` is `false`). See [The waitlist](https://docs.bifrostorbit.com/booking/everyone/waitlist/).

```http
GET /offers/<token>
```

Reads an offer from that email: `token`, `service`, `staffId`, `staff`, `startsAt`, `expiresAt` and `customer`. To book it, send `POST /appointments` with the offer's `token` as `holdToken`. `404` means the offer has run out or was taken.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid` | A required parameter is missing, or an answer doesn't fit its question |
| 402 | `subscription_inactive` | The location is paused because the plan has ended |
| 403 | `forbidden` | A change from a website that isn't allowed, a change too close to the start, or a waitlist the location doesn't keep |
| 404 | `not_found` | The location, service, appointment or offer doesn't exist |
| 409 | `conflict` | The time has gone, the hold ran out, a daily limit was reached, or the appointment is already over or cancelled |
| 409 | `payment_required` | The service is paid online when it's booked. Send the customer to `bookingUrl`. See **Services paid online** above. |
| 422 | `invalid` | A field is missing or in the wrong format. `issues` lists them. |
| 429 | `rate_limited` | Too many tries. Wait a minute. |
| 500 | `server_error` | Something went wrong on our side. Try again. |
| 503 | `unavailable` | Booking Orbit is restarting after an update. Try again after a few seconds. |

[Troubleshooting](https://docs.bifrostorbit.com/booking/developers/troubleshooting/) has every message with its fix.
