Book an appointment
/api/v1/appointmentsBooks an appointment for a client through the booking page's own writer: the time is re-checked against working hours, rotation, overrides, venue and special hours, blocks and the booking window, and the database refuses an overlap. The client gets the business's usual confirmation. The booking's source is api.
Idempotency-Key header required: a UUID you generate once per booking attempt and resend unchanged on every retry. The first answer is stored and every retry with the same key, from the same API key, with the same body gets that answer back, so a retried create never books twice. The same UUID with a different body, or from a different API key, is a 409. Stored answers include refusals: a 409 for a taken time replays as a 409, so a new attempt needs a new key. Answers are kept for at least a day.
A business that takes a deposit or a card is answered 402 payment_required with a link, never with an unpaid booking. The client's marketing consent is never set by this call.
Authorization
bearerApiKey appointments:writeBuild with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.
In: header
Scope: appointments:write
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/appointments" \ -H "Content-Type: application/json" \ -d '{ "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24", "startsAt": "string", "customer": { "name": "string", "email": "user@example.com" } }'{ "data": {}}List appointmentsGET
The appointments engine's bookings, newest first. Use `from` and `to` to ask for a day or a week. They are why this is one of only two v1 lists with filters: services, staff, tables and service periods are bounded by how many a business has, so one page is the whole list, while bookings are unbounded and time-shaped. Engine-guarded: a key from a table-reservations organization gets `403 wrong_vertical`, and `appointments:*` scopes cannot be granted to one in the first place. **Times.** `startsAt` and `endsAt` are the venue's local time with its real offset (`2026-08-20T19:00:00+10:00`), so they parse to the true instant like `createdAt` does. `from` and `to` are venue-local wall clock; any offset on them is ignored.
List servicesGET
The appointments engine's bookable services. Engine-guarded: a key from a table-reservations organization gets `403 wrong_vertical` even if it holds `services:read`; the boundary is about what the organization is, not what happens to be stored for it. **Ordered by `id`, which is stable but arbitrary.** A business sells tens of services, so the first page of 200 is the whole list in practice; sort them yourself if you want them alphabetical. `active: false` services ARE returned, so a program reconciling against its own copy sees a service that was switched off instead of having it silently disappear. The public booking endpoints are where inactive services are filtered out.