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.
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 status200, or201when 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 answer422withissues, the list of fields that failed, each with itspathand amessagein 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 areYYYY-MM-DD. - Money is in the currency's smallest unit:
45000withNOKis NOK 450. - Ids or short names: Wherever a service is asked for, you can send its
idor itsslug, such asboot-fitting. - Language:
localepicks 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
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:
/, /services, /services/<service>, /staff, /slots/holds, DELETE/holds/<token>/appointments and POST/waitlist together/manage/<token>, and GET/offers/<token>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
GET /localeintro.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.cancelUntilHourspolicies.rescheduleUntilHourspolicies.requireApprovalbookingPage.showStafffalse, /staff is empty.bookingPage.showPricesfalse, every service's price is { "kind": "hidden", "amount": null }.bookingPage.phone, bookingPage.notesrequired, optional or hiddenbookingPage.waitlistbookingPage.marketingmarketing.bookingPage.termsUrl, bookingPage.privacyUrlServices
GET /servicesAnswers { "services": [...] }, the services listed on the booking page, in their order. Each service has:
id, slug, name, description, category, imageUrldurationMinutesmodein-person, online or eitherpricekind: free, fixed, from or hidden, and amountpaymentrule: 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.capacitystaffIdsformIdnullServices shown only With a link are left out, but you can read and book them by id or short name.
GET /services/<service>localeAnswers { "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
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
GET /slots?service=<service>servicestafffromYYYY-MM-DD. Today if left out or in the past.daystimeZoneEurope/Oslo, so days start and end at the customer's midnight. The location's own if left out.manage{ "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
POST /holds{ "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.
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
POST /appointmentsservicestartsAtholdToken409 if the hold has run out or is for another time.staffnameemailphonebookingPage.phone is required, ignored when it's hiddennotesbookingPage.notes is hidden.answersid. Send option ids for choice (one) and choices (a list), true or false for yes-no and consent, and YYYY-MM-DD for date.marketingtrue if the customer wants news, when bookingPage.marketing is on.localetimeZoneAnswers 201 with appointment and payment:
{ "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 } }}statusisconfirmed, orpendingwhen the location confirms bookings itself.manageUrlis 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.icsis a path on the Booking Orbit address.googleandoutlookadd the appointment to those calendars.meetingUrlis the video link for online appointments, once there is one.payment.methodisnone,at-location(paid at the location) oronline.
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:
{ "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.
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.
POST /manage/<token>/reschedule{ "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.
POST /manage/<token>/cancel{ "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.
GET /manage/<token>/calendarAnswers the appointment as a calendar file, text/calendar, named after its reference, such as 29BMJM.ics.
Waitlist
POST /waitlist{ "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.
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
invalidsubscription_inactiveforbiddennot_foundconflictpayment_requiredbookingUrl. See Services paid online above.invalidissues lists them.rate_limitedserver_errorunavailableTroubleshooting has every message with its fix.
Was this page helpful?