Skip to content
BookFlow

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.

Request header
Authorization: Bearer bf_live_xxxxxxxxxxxxxxxxxxxxxxxx

List services

GET/api/v1/services?page=your-page

Returns the services and staff members you can book.

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

Example response
{
  "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.

Example
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." }
StatusMeaning
400Invalid input, with a code such as invalid_email or invalid_date
401Missing or unknown API key
403Your plan does not include API access, or it is not active
404No such page, service or booking on your account
409slot_taken, not_accepting (page paused or booking limit reached) or not_confirmed
429Too 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.

Payload
{
  "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.

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