Skip to content

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.

Reference13 min read

The public booking API is what the booking page, the widget and the Booking SDK use. It is plain JSON over HTTPS, so you can call it from any language.

The public booking API reference 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, 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

Reading: the location, services, people and free times
From your server
Yes
From a browser
From any website
Changing: holds, bookings, the waitlist, and reading or changing one appointment
From your server
Yes
From a browser
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.

Rate limits

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

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

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

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>
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>
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
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 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.

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

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

Troubleshooting has every message with its fix.

Was this page helpful?

Read next