Wellness Frontier · Developers
Build on a salon's Online Booking
Every salon with Online Booking has a booking page. With the salon's key you can show its free times and take bookings in your own site or app, and with a webhook you hear about every booking as it is made, moved or cancelled. The salon's rules always apply: the same hours, notice and team as on its page.
Getting started
- The salon's owner opens Online Booking › Settings › For developers and creates a key, choosing
read,bookor both. - They copy the key once and give it to you. It starts
wf_live_. - Ask for free times, then book one of them.
curl "https://wellnessfrontier.co/api/v1/booking/availability?serviceId=<service id>&day=2026-11-12" \ -H "Authorization: Bearer wf_live_…"
Only need a Book now key on a website? The embed script needs no key at all.
Authentication
Send the key in the Authorization header as Bearer wf_live_…. A key belongs to one salon; it can only ever reach that salon.
Scopes
read: Services, professionals and free times (GET availability).book: Create bookings (POST bookings).
Keeping keys safe
- We keep only a fingerprint of each key, so a lost key can't be shown again: the owner revokes it and makes a new one.
- Keyed calls answer any website (CORS), and send no cookies. A
readkey may sit in a web page; keep abookkey on your server. - A revoked key stops working at once.
Free times
GEThttps://wellnessfrontier.co/api/v1/booking/availabilityKey scope: read
The salon, its services and professionals; with serviceId and day, that day's free start times too.
Query
serviceIdstringA service's id from
services. With day, the answer includes free times.dayYYYY-MM-DDThe salon's day, in its own time zone. Without it, today.
professionalIdstringA professional's id, or
anyone (the default) for the first one free.locationIdstringOne of
salon.locations. Without it, the salon's main location.Answer
oktrueAlways true on a 200.
salonSalonThe salon, its time zone, brand and locations.
servicesService[]What clients can book.
professionalsProfessional[]Who can be booked (for the chosen service, when one is given).
dayYYYY-MM-DDPresent when
serviceId and day were asked for.slotsSlot[]Free start times that day, with who is free at each. Empty while the page is paused.
Salon
slugstringThe page's name, as in
<slug>.wellnessfrontier.vip.namestringThe salon's trading name.
timeZoneIANA zoneShow every time in this zone, e.g.
Africa/Johannesburg.templateIdstringThe booking page's template.
brandBrandLogo, cover and room photo URLs (ours), and the two brand colours.
currencyISO 4217 | nullThe currency of
priceCents. Null: show no prices.acceptingBookingsbooleanFalse while the page is paused.
locations{ id, name }[]The salon's locations.
cancellationNoticeHoursnumberHow much notice the salon asks for a cancellation.
Service
idstringPass as
serviceId.namestringThe service's name.
categorystring | nullIts category, for grouping.
durationMinutesnumberThe whole time held, in minutes.
priceCentsnumber | nullThe client's price in cents of
salon.currency; null when not shown.Professional
idstringPass as
professionalId.namestringAs the salon shows names: "Thandi N." by default.
Slot
startsAtISO 8601 (UTC)Pass exactly as
startsAt to book.professionalIdsstring[]Who is free then.
Bookings
POSThttps://wellnessfrontier.co/api/v1/booking/bookingsKey scope: book
Books one of the offered times. The salon and client get the same confirmation emails as from the booking page, and the booking appears in the salon's Scheduler.
Body
serviceIdrequiredstringA service's id.
professionalIdrequiredstringA professional's id, or
anyone.startsAtrequiredISO 8601One of the offered
slots[].startsAt.locationIdstringWithout it, the salon's main location.
clientrequiredClientWho is coming. An existing client with this email or mobile is matched; their saved details never change.
websitestringLeave out. A form's hidden trap field: any value is treated as a bot.
Client
firstNamerequiredstringUp to 100 characters.
lastNamerequiredstringUp to 100 characters.
emailrequiredstringWhere the confirmation goes.
mobilerequiredstring7 to 20 digits, with or without spaces and +.
curl -X POST "https://wellnessfrontier.co/api/v1/booking/bookings" \
-H "Authorization: Bearer wf_live_…" \
-H "Content-Type: application/json" \
-d '{"serviceId":"5b1d0c3e-2f4a-4d0b-9a51-0c9e7f3a1b22","professionalId":"anyone","startsAt":"2026-11-12T08:00:00.000Z","client":{"firstName":"Lerato","lastName":"Mokoena","email":"lerato@example.com","mobile":"+27 82 555 0101"}}'Answer (201)
oktrueAlways true on a 201.
referencestringThe short reference the client can quote, e.g.
WF-7K3QX2.startsAtISO 8601 (UTC)When it starts.
endsAtISO 8601 (UTC)When it ends.
serviceNamestringThe service booked.
professionalNamestringWho it is with, as the salon shows names.
salonNamestringThe salon.
timeZoneIANA zoneThe salon's time zone.
cancellationNoticeHoursnumberThe salon's cancellation notice.
{
"ok": true,
"reference": "WF-7K3QX2",
"startsAt": "2026-11-12T08:00:00.000Z",
"endsAt": "2026-11-12T09:00:00.000Z",
"serviceName": "Signature facial",
"professionalName": "Thandi N.",
"salonName": "Salon Le Fresh",
"timeZone": "Africa/Johannesburg",
"cancellationNoticeHours": 24
}Errors
Every error has the same shape: { "ok": false, "code": "…", "error": "plain words" }. Show error to people; branch on code.
unauthorizedHTTP 401No key, a malformed key, or a revoked key.
forbiddenHTTP 403The key doesn't have the scope this endpoint needs.
not_foundHTTP 404The salon's page isn't open (not published, taken down, or the app isn't installed).
pausedHTTP 409The page is paused: it shows, but takes no bookings.
invalid_requestHTTP 400Something is missing or not right;
error says what.outside_rulesHTTP 422The time is outside the salon's rules: too soon, too far ahead, or not an offered time.
slot_takenHTTP 409Someone took the time first. Ask for free times again.
rate_limitedHTTP 429Too many calls. Wait for
Retry-After seconds.unavailableHTTP 503Something went wrong on our side. It has been reported; try again shortly.
Rate limits
- Per key: 300 free-time calls a minute, and 60 bookings every 10 minutes.
- Without a key (the booking page and embed): 120 free-time calls a minute and 6 bookings every 10 minutes, per visitor.
- Over the limit you get
429 rate_limitedwith aRetry-Afterheader in seconds.
Webhooks
The owner adds an https endpoint in Online Booking › Settings › For developers, chooses its events, and gets a signing secret (shown once). We send a POST with a JSON body for each event.
Events
booking.created: A booking was made: online (the booking page, the embed or the API) or in the Scheduler.booking.moved: A booking's time changed in the Scheduler.booking.cancelled: A booking was cancelled (on time or late).
Body
idstring
evt_…, the same on every retry: use it to ignore a repeat.typestringOne of the three events.
createdAtISO 8601 (UTC)When the change happened.
testbooleanTrue only for Send test event, whose booking is made up.
salon{ slug }The salon's page name (null if it has none yet).
data{ booking }The booking as it is now.
Booking
idstringThe booking's id in the Scheduler.
referencestringThe client's reference, e.g.
WF-7K3QX2.statusstring
confirmed, cancelled, late_cancel and the Scheduler's other states.startsAtISO 8601 (UTC)When it starts.
endsAtISO 8601 (UTC)When it ends.
locationIdstringWhere.
source"online" | "scheduler"Where the change came from.
services{ serviceId, serviceName, professionalId, startsAt, endsAt }[]Each service, in order.
client{ id, firstName, lastName } | nullThe main client. No contact details travel in webhooks.
{
"id": "evt_3f0c9d6a1b2e4f5a8c7d6e5f4a3b2c1d",
"type": "booking.created",
"createdAt": "2026-11-01T09:14:03.000Z",
"test": false,
"salon": {
"slug": "salon-le-fresh"
},
"data": {
"booking": {
"id": "7a3c1e2b-9d4f-4a6b-8c5d-2e1f0a9b8c7d",
"reference": "WF-7A3C1E",
"status": "confirmed",
"startsAt": "2026-11-12T08:00:00.000Z",
"endsAt": "2026-11-12T09:00:00.000Z",
"locationId": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
"source": "online",
"services": [
{
"serviceId": "5b1d0c3e-2f4a-4d0b-9a51-0c9e7f3a1b22",
"serviceName": "Signature facial",
"professionalId": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"startsAt": "2026-11-12T08:00:00.000Z",
"endsAt": "2026-11-12T09:00:00.000Z"
}
],
"client": {
"id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
"firstName": "Lerato",
"lastName": "Mokoena"
}
}
}
}Signature
Each delivery carries WF-Signature, WF-Event and WF-Event-Id. The signature is t= (unix seconds) and v1=, the hex HMAC-SHA256 of <t>.<raw body> with your secret. Refuse anything older than 5 minutes.
WF-Signature: t=1793524443,v1=5f2b…
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body exactly as received (before JSON.parse).
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Delivery
- Answer with any 2xx within 8 seconds. Do slow work afterwards.
- No answer, a timeout, 408, 429 or 5xx: we try again after 2 and 10 seconds. Other answers and redirects are not retried.
- The same event can arrive twice; use its
idto ignore a repeat. Events may arrive out of order;createdAttells you which came first. - A booking never waits for your endpoint. The owner sees each endpoint's last delivery, and can send a test event with a made-up booking (
test: true). - Endpoints must be public https addresses; private networks are never called.
Embed script
One line puts the salon's booking page on any website. No key needed.
<script src="https://wellnessfrontier.vip/embed.js" data-salon="salon-le-fresh" async></script>
data-salonsalon-le-freshRequired. Your booking page's name.
data-modeinline
inline puts the page into your site; otherwise a floating Book now key opens it over your site.data-target#bookingWith
inline: a CSS selector for where the page goes. Without it, right where the tag sits.data-height720With
inline: the starting height in pixels; the page then sizes itself.data-labelBook a treatmentThe key's words, up to 40 characters. Book now by default.
data-colour#2f5d50The key's colour as a hex value (
data-color works too).data-positionleft
left puts the floating key bottom left; bottom right by default.data-wf-bookattributePut on any button or link of yours to open the same booking overlay.
When a client books, your page gets a wellnessfrontier:booked event on document, with detail: { salon, reference }.
document.addEventListener("wellnessfrontier:booked", (event) => {
console.log("Booked", event.detail.reference);
});Help
- Where Book now works without code: Works with.
- Something not right? Quote the
WF-reference or the time of the call, and ask the salon's owner to contact us through AIVA in their Wellness Frontier. - Changes to this API are added alongside what is here; nothing you rely on is removed without notice to every salon with a key.