List appointments
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.
Authorization
bearerApiKey appointments:readBuild 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:read
Query Parameters
Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A ?limit=1e9 from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop.
1 <= value <= 20050The nextCursor from the previous response, passed back unchanged. Omit it for the first page. Opaque: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a 400 invalid_cursor rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.
The scheme is keyset (seek) paging on (order column, id), not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and limit may change between pages; the cursor only says where you got to.
Inclusive lower bound on startsAt. Any timestamp Postgres accepts; a value it rejects is a 400. Combine with to for a day or a week.
Compared against startsAt, so it is in the venue's wall clock, not UTC, whatever offset you write on it. from=2026-08-20T00:00:00Z means midnight at the venue, not midnight UTC, and the Z is not honoured. To ask for a venue's day, write that day's local midnight and ignore the offset. Asking in real UTC instead returns a window shifted by the venue's offset, which for an Australian venue is most of a different day.
date-timeEXCLUSIVE upper bound on startsAt. Exclusive so that from=2026-07-26T00:00:00&to=2026-07-27T00:00:00 is exactly one day with no double-counting at the seam. That day is the venue's, not UTC: like from, this is compared against the venue's wall clock and any offset you write is ignored.
date-timeResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/appointments"{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "startsAt": "2019-08-24T14:15:22Z", "endsAt": "2019-08-24T14:15:22Z", "status": "pending", "durationMinutes": 0, "price": 0, "notes": "string", "serviceId": "8f8bb40f-b96b-40fe-9064-5031fbe483f9", "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24", "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac", "depositStatus": "none", "depositAmountCents": 0, "createdAt": "2019-08-24T14:15:22Z", "reconfirmRequestedAt": "2019-08-24T14:15:22Z", "reconfirmedAt": "2019-08-24T14:15:22Z" } ], "nextCursor": "string"}API reference
All 45 public operations, grouped by product area.
Book an appointmentPOST
Books 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.