API
API documentation
A small REST API to read services and availability and to create and cancel bookings from your own software. Included in the Enterprise plan.
Overview
The API is JSON over HTTPS. The base URL is https://bookflow.com/api/v1. Times are ISO 8601 in UTC. Every request acts on booking pages of the account that owns the API key. If your account has several booking pages (locations), pass page with the link name of the page; without it the oldest page is used.
API access needs an active Enterprise plan. Create and revoke keys in the API tab of your dashboard.
Authentication
Send your key in the Authorization header. A key is shown once when you create it and only its hash is stored. Call the API from your server, never from a public web page.
Authorization: Bearer bf_live_xxxxxxxxxxxxxxxxxxxxxxxxList services
GET/api/v1/services?page=your-page
Returns the services and staff members you can book.
curl https://bookflow.com/api/v1/services?page=north-location \
-H "Authorization: Bearer $BOOKFLOW_KEY"
{
"page": "north-location",
"timezone": "Europe/Paris",
"currency": "EUR",
"services": [
{ "id": "5b1c...", "name": "Session", "durationMinutes": 60, "priceCents": 9000, "description": "" }
],
"staff": [{ "id": "a91f...", "name": "Amira" }]
}Check availability
GET/api/v1/availability?service=ID&from=YYYY-MM-DD&days=7&staff=ID
service is required. from is a date in the booking page time zone (default today), days is 1 to 31 (default 7), staff is optional. Each slot lists the staff members who are free at that start time.
{
"page": "north-location",
"timezone": "Europe/Paris",
"slots": [
{ "start": "2026-12-01T08:00:00.000Z", "staffIds": ["a91f..."] },
{ "start": "2026-12-01T09:00:00.000Z", "staffIds": ["a91f...", "c07d..."] }
]
}Create a booking
POST/api/v1/bookings
Books a start time returned by the availability call. staff is optional: without it the first free staff member is used. The client receives the confirmation email.
curl -X POST https://bookflow.com/api/v1/bookings \
-H "Authorization: Bearer $BOOKFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{
"page": "north-location",
"service": "5b1c...",
"start": "2026-12-01T09:00:00.000Z",
"name": "Alice Client",
"email": "alice@example.com",
"phone": "+33 6 12 34 56 78",
"notes": "First visit",
"timezone": "America/New_York"
}'
201 Created
{
"booking": {
"id": "e3a2...", "page": "north-location", "status": "confirmed",
"service": { "id": "5b1c...", "name": "Session" },
"staff": { "id": "a91f...", "name": "Amira" },
"start": "2026-12-01T09:00:00.000Z", "end": "2026-12-01T10:00:00.000Z",
"timezone": "Europe/Paris",
"client": { "name": "Alice Client", "email": "alice@example.com", "phone": "+33 6 12 34 56 78" },
"notes": "First visit", "source": "api"
}
}If the time was taken in the meantime the API answers 409 with the error code slot_taken. Check availability again.
List bookings
GET/api/v1/bookings?from=ISO&to=ISO&status=confirmed
Defaults to the last 7 days and the next 60 days. The range can span at most 400 days and the list returns up to 500 bookings. status is one of confirmed, cancelled, completed, no_show.
Cancel a booking
POST/api/v1/bookings/:id/cancel
Cancels a confirmed booking and sends the client a cancellation email. Answers 409 if the booking is not active.
curl -X POST https://bookflow.com/api/v1/bookings/e3a2.../cancel -H "Authorization: Bearer $BOOKFLOW_KEY"
{ "ok": true }Errors and limits
Errors are JSON with a stable code and a readable message. Use the HTTP status first and the code second.
{ "error": "slot_taken", "message": "That time is no longer available. Please pick another." }| Status | Meaning |
|---|---|
| 400 | Invalid input, with a code such as invalid_email or invalid_date |
| 401 | Missing or unknown API key |
| 403 | Your plan does not include API access, or it is not active |
| 404 | No such page, service or booking on your account |
| 409 | slot_taken, not_accepting (page paused or booking limit reached) or not_confirmed |
| 429 | Too many requests: 600 per 15 minutes per key. Wait and retry |
Webhooks
On the Team and Enterprise plans, set a webhook address (https only) in the Booking page tab. BookFlow sends one POST for each booking.created and booking.cancelled event, without retries. It works with a Zapier or Make “catch hook” address.
{
"event": "booking.created",
"createdAt": "2026-11-30T14:03:11.204Z",
"data": { "id": "e3a2...", "page": "north-location", "status": "confirmed", "start": "2026-12-01T09:00:00.000Z", "...": "same shape as the booking object above" }
}Each request has the header X-BookFlow-Signature: sha256=<hex>, an HMAC SHA-256 of the raw request body using the signing secret shown next to the webhook address. Check it before you trust the message.
import { createHmac, timingSafeEqual } from "node:crypto";
function isValid(rawBody, header, secret) {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(header || "");
return a.length === b.length && timingSafeEqual(a, b);
}Respond with any 2xx status within 8 seconds. Delivery is best effort, so for anything critical also read bookings through the API.