Book'd Out APIv1

A REST API and outbound webhooks for connecting your own tools to your Book'd Out account. Read your calendar, create bookings, sync customers, and receive events the moment they happen.

Overview

The base URL is https://www.bookdout.com/api/v1. The /api/v1 surface is stable: we only make additive changes (new endpoints, new optional fields). Breaking changes would ship as a new version prefix.

API access and webhooks are included in the Bookings Pro plan. Keys belong to one business, so every request operates on your own account and there is no account parameter to pass.

Authentication

Create keys in your admin under Settings, then Developer. Each key is shown once at creation; we store only a hash. Send the key as a bearer header on every request:

curl https://www.bookdout.com/api/v1/me \
  -H "Authorization: Bearer bko_live_your_key_here"

• Scopes: read (GET endpoints) and read_write (adds the POST endpoints). A read-only key on a write endpoint gets 403 insufficient_scope.
• Keys are never accepted in the URL. A request with an api_key query parameter is rejected so keys cannot leak into logs.
• Treat keys like passwords. To rotate, create a new key, switch your integration over, then revoke the old one. Revocation is immediate.

Rate limits

• 300 requests per minute per key across all endpoints.
• 60 writes per minute per key on POST endpoints, counted on top of the request limit.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you exceed a limit you get 429 rate_limited with a Retry-After header holding the seconds until the window resets.

Conventions

• JSON in and out, camelCase field names.
• Timestamps are ISO 8601 UTC (for example 2026-08-01T00:30:00.000Z). Responses that involve local times also include the business's IANA timezone.
• List endpoints paginate with ?page=N (1-based, 50 rows per page) and return { "data": [...], "page": N, "hasMore": true|false }.
• Request bodies are capped at 4 KB.

Errors

Errors use one envelope: { "error": "<code>", "message": "<human text>" }.

Endpoint reference

Create a booking

Pick a slot from /api/v1/availability and post its exact start. Pass "staffId": "any" (or omit it) to let the engine assign a team member, exactly as the online booking page does.

curl -X POST https://www.bookdout.com/api/v1/appointments \
  -H "Authorization: Bearer bko_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "serviceId": 12,
    "staffId": "any",
    "start": "2026-08-01T00:30:00.000Z",
    "customer": { "name": "Sam Taylor", "email": "[email protected]" },
    "notifyCustomer": true
  }'

A successful create returns 201 with the full appointment. If the slot was taken in the meantime you get 409 slot_taken; fetch availability again and retry with a fresh slot. Set "notifyCustomer": false to suppress the confirmation email.

Not yet in v1 (planned): rescheduling via PATCH, sales and payment writes, managing webhook endpoints through the API, and OAuth apps. Webhook endpoints are managed in the admin for now.

Idempotency

POST /appointments and POST /customers accept an optional Idempotency-Key header (1 to 255 characters, any string unique to the operation). If a request is retried with the same key and the same body within 24 hours, the stored response is returned verbatim with the header Idempotency-Replayed: true, and no duplicate booking is created. The same key with a different body returns 422 idempotency_conflict. If the first request is still in flight you get 409 idempotency_in_progress; retry shortly.

Webhooks

Register up to 5 endpoints under Settings, then Developer. Each endpoint gets its own signing secret (whsec_...) and its own event subscription list. We POST a JSON body to your URL:

{
  "event": "appointment.created",
  "createdAt": "2026-08-01T00:30:05.123Z",
  "data": {
    "appointment": { "id": 91, "status": "confirmed", "startAtUtc": "..." },
    "changeKind": "created"
  }
}

Event types

Verifying signatures

Every delivery carries three headers: Bookd-Event (the event type), Bookd-Delivery-Id (unique per delivery), and Bookd-Signature in the form t=<unix seconds>,v1=<hex HMAC>. The signature is HMAC-SHA256 of <t>.<raw body> using your endpoint secret:

const crypto = require('node:crypto');

function verify(signatureHeader, rawBody, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('=')),
  );
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > 300) return false; // reject anything older than 5 minutes
  const expected = crypto.createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex'),
  );
}

• Use a constant-time compare, as above.
• Reject deliveries whose timestamp is more than 5 minutes old.
• Delivery is at least once. Deduplicate on Bookd-Delivery-Id: if our timeout fires after your server received the event, the redelivery reuses the same id.
• Respond with a 2xx quickly and process the event asynchronously. We time out after 10 seconds.

Retries and disabling

A non-2xx response or a timeout is retried on a backoff of 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, then 24 hours. After the final retry the delivery is marked dead; you can replay it from the delivery log in the admin. An endpoint that fails 50 deliveries in a row is disabled automatically and can be re-enabled from the same page once your receiver is fixed.

Changelog

• 20 July 2026: initial release of /api/v1 (me, services, staff, availability, appointments, customers, reviews) and webhooks (six event types, signed deliveries, retries, replay).