Bookings

Bookings covers the appointment: someone picks a moment, leaves their details, and both sides get an email. It is deliberately small. It knows when the venue takes bookings and which start times are still free for an appointment of a given length — and it tells a website only the times, never who booked the others. If you need tables, party sizes and capacity, that is Reservations.

When bookings are taken#

{
  "ok": true,
  "contract": 1,
  "data": {
    "timezone": "Europe/Amsterdam",
    "accepting": true,
    "days": [
      { "date": "2026-10-09", "open": "09:00", "close": "17:00" },
      { "date": "2026-10-10", "closed": true }
    ]
  }
}

These are the same hours a booking from a key is held to, read the same way, so a day open here is a day requestBooking takes and a closed one is a day it refuses. An open day carries open and close as HH:mm; a booking may start at open or any minute after it, up to but not at close. A day whose hours close at or before they open is closed: true, because no minute of it can be booked. accepting: false means the venue has switched booking requests off: every booking from a key is refused until it switches them back on, whatever the hours say.

Without from the answer is never cached, because "today" moves at midnight. With from it may be kept for a minute, which is how long a merchant's change to their hours can take to show. If the hours cannot be read the answer is 503 HOURS_UNAVAILABLE, never an empty week that would read as closed every day.

Free start times#

{
  "ok": true,
  "contract": 1,
  "data": {
    "timezone": "Europe/Amsterdam",
    "accepting": true,
    "duration_minutes": 45,
    "step_minutes": 15,
    "buffer_minutes": 0,
    "lead_minutes": 120,
    "days": [
      { "date": "2026-10-13", "closed": false, "slots": ["16:00", "16:15", "17:30", "19:45", "20:00", "20:15"] },
      { "date": "2026-10-14", "closed": true, "slots": [] }
    ]
  }
}

A start is offered when the whole appointment fits inside that day's hours — it may end exactly at closing time — when it is later than now and at least lead minutes away, and when the appointment plus buffer overlaps no booking plus buffer. The hours are the ones above, exceptions included, so a day hours calls closed is closed: true here. An open day with nothing left is closed: false with an empty slots: that is fully booked, not closed. While accepting is false every day has an empty slots, because every booking from a key would be refused.

What holds time is a booking that is pending or accepted. A request from a website holds its time from the moment it arrives, before the venue has looked at it; a declined, cancelled or completed one does not, and neither does one the spam screening held back. Each holds as long as its duration_minutes, and an hour when it has none — which is every booking made without one, by the dashboard or by a site that does not send it.

Never cached: this is occupancy, and a time that was taken a minute ago must not be on offer. If the bookings or the hours cannot be read the answer is 503 AVAILABILITY_UNAVAILABLE, never an empty calendar. It narrows double-booking and does not lock anything: two visitors who pick the same time at the same moment can both send it. Ask again for that one day just before you post the booking, and tell the visitor the time was just taken when it is gone.

Creating a booking#

{
  "name": "Noor van Elderen",
  "email": "noor@example.com",
  "phone": "+31 6 12 34 56 78",
  "date": "2026-09-14",
  "time": "14:30",
  "meeting_type": "video-call",
  "message": "Would prefer the afternoon if possible."
}

A field that breaks one of these rules is 400 VALIDATION_ERROR with the message Validation failed, whatever the rule; which field it was, and why, is in details — "Name must be at most 255 characters", "Phone number must be at most 50 characters". Keys the booking does not know are not refused and not stored: the 201 names them in data.ignored_fields, in the order you sent them, and leaves it out when there are none. A remark sent as notes rather than message is in that list, and did not arrive.

The organization comes from the API key. Do not send one in the body: it is taken out of band, and a body field would only be a second source of truth. An organization_id sent anyway is not read, and is in ignored_fields.

What a website is held to

A booking made with a key is a website asking, and it is held to the venue's calendar. Each refusal has a code of its own beside a sentence written for your logs; branch on the code and write the visitor's words yourself.

Staff booking from the dashboard are held to none of these but the date: a phone call for a time the venue is technically shut is still a real appointment, and a booking can be written down after the fact.

What comes back

The stored booking, as a key reads it everywhere: id, organization_id, the fields above, status, created_at and updated_at. duration_minutes is always there, null for a booking made without one. time is HH:mm — the dashboard reads the same column with seconds, 14:30:00, and a key does not. A key does not get what the spam screening and the provenance record write: quarantined_at, spam_signals, source_channel, source_host and source_api_key_id are the dashboard's.

status is where the booking stands: pending for one a website made, until the venue accepts it, then accepted, declined, completed or cancelled. Staff move it from the dashboard; a booking made there starts as accepted. Nothing a key can call changes it.

Reading bookings#

Useful for a back-office sync or a customer-facing "your appointments" page behind your own login. It is not something a public storefront needs — not even for a calendar, which is what availability is for — and a storefront key should not carry the scope. A startDate or endDate that is not a day is 400 INVALID_DATE.

A key does not see bookings the spam screening held back. They are left out of the list, and pagination.total, totalPages and hasMore are counted without them. The dashboard sees them.

An id that names no booking of this organization is 404 BOOKING_NOT_FOUND, and so is an id that is not a uuid, and — for a key — a booking the spam screening held back: word for word the answer to an id nobody has. Changing or removing a booking is dashboard work, and a key is refused there.

Reminders#

There is nothing to call from a website. This is the dashboard's button, for the signed-in organization and no other; a key is answered as a call without a session. And it sends nothing at all unless the server runs with REMINDERS_ENABLED=true. The automated run exists and is not scheduled, so today no reminder goes out on its own — do not promise one on your confirmation page.

/api/bookings/reminders takes POST only: a GET is not an endpoint there. The automated run is a different route, the booking-reminders cron, and it is internal: it answers GET because that is the verb Vercel Cron sends (and POST, which does the same), only with Authorization: Bearer <CRON_SECRET>, and it is no API for a site or a key. It is off by default too (REMINDERS_ENABLED), and nothing schedules it today.

Building a booking form#

1. 01

   Ask for the free times

   Read availability with the length of what the visitor chose, worked out on your server, for the weeks you show. Grey out the closed days, offer only the times in slots, and show the phone number instead of the calendar while accepting is false. Without a calendar, hours is enough for a request form.

2. 02

   Collect the six required fields

   Name, email, phone, date, time and meeting type. Label above input, error below, no placeholder standing in for a label. Add the hidden honeypot field and post whatever lands in it.

3. 03

   Post from your server

   The key must not be in the browser. Your form posts to your own route, which asks availability for that one day again and then posts to Cnter — with duration_minutes, so the booking holds as long as the appointment takes.

4. 04

   Confirm without promising

   Say the request is in and that a confirmation is on its way. It arrives as pending, and your customer decides what happens next.

5. 05

   Handle the 400 inline

   Branch on the code. For VALIDATION_ERROR, details[].path names the field: put your own sentence next to it rather than in a toast. For DATE_CLOSED, OUTSIDE_OPENING_HOURS and START_TIME_IN_PAST, ask for another moment.