Make a booking
const url = 'https://example.kwickbooking.com/public/v1/reservations';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"venueId":"01920000-0000-7000-8000-000000000001","date":"2026-10-16","time":"20:00","partySize":4,"bookingTypeId":"01920000-0000-7000-8000-000000000003","guest":{"name":"Sam Patel","phone":"07911 123456","email":null},"notes":null}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.kwickbooking.com/public/v1/reservations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "venueId": "01920000-0000-7000-8000-000000000001", "date": "2026-10-16", "time": "20:00", "partySize": 4, "bookingTypeId": "01920000-0000-7000-8000-000000000003", "guest": { "name": "Sam Patel", "phone": "07911 123456", "email": null }, "notes": null }'Books a free time for a named guest with a phone number. The booking’s source is the key’s channel. When the venue’s policy asks for a deposit, the booking is held and a payment link goes to the guest automatically. If the time is gone the answer is unavailable with alternatives; a party larger than the venue takes online is needs_venue. Send an Idempotency-Key header.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”POST /public/v1/reservations: book PartySize at Time
on Date (venue-local) for Guest. The booking’s source is
always the key’s channel.
object
The guest a booking is for: a name and a phone number, optionally an email.
object
Example
{ "venueId": "01920000-0000-7000-8000-000000000001", "date": "2026-10-16", "time": "20:00", "partySize": 4, "bookingTypeId": "01920000-0000-7000-8000-000000000003", "guest": { "name": "Sam Patel", "phone": "07911 123456", "email": null }, "notes": null}Responses
Section titled “Responses”OK
The answer to a booking request, with a summary to read out.
object
The deposit on a new booking: whether one is due, how much, whether it is awaiting payment,
where the link went (text, email or text and email) and when it
expires (venue-local yyyy-MM-ddTHH:mm).
object
Another time, day or venue that fits when the asked one doesn’t.
object
A booking type that fits a time, with its length and deposit.
object
A deposit as a guest would hear it.
object
Examplegenerated
{ "outcome": "example", "reference": "example", "state": "example", "venueId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "date": "example", "time": "example", "partySize": 1, "bookingType": "example", "durationMinutes": 1, "deposit": { "required": true, "amountPence": 1, "amountDisplay": "example", "status": "example", "sentTo": "example", "linkExpiresAt": "example" }, "alternatives": [ { "venueId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "venueName": "example", "date": "example", "time": "example", "options": [ { "bookingTypeId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "bookingType": "example", "durationMinutes": 1, "deposit": { "required": true, "amountPence": 1, "amountDisplay": "example" } } ] } ], "summary": "example"}Created
The answer to a booking request, with a summary to read out.
object
The deposit on a new booking: whether one is due, how much, whether it is awaiting payment,
where the link went (text, email or text and email) and when it
expires (venue-local yyyy-MM-ddTHH:mm).
object
Another time, day or venue that fits when the asked one doesn’t.
object
A booking type that fits a time, with its length and deposit.
object
A deposit as a guest would hear it.
object
Example
{ "outcome": "booked", "reference": "48271936", "state": "confirmed", "venueId": "01920000-0000-7000-8000-000000000001", "date": "2026-10-16", "time": "20:00", "partySize": 4, "bookingType": "Table booking", "durationMinutes": 120, "deposit": { "required": false, "amountPence": 0, "amountDisplay": "£0.00", "status": "not_required", "sentTo": null, "linkExpiresAt": null }, "alternatives": [], "summary": "Booked: Fri 16/10 at 20:00 for 4. Reference 4827 1936."}Venue required (https://developers.kwickblocks.ai/problems/venue-required); Validation failed (https://developers.kwickblocks.ai/problems/validation-failed); Idempotency-Key required (https://developers.kwickblocks.ai/problems/idempotency-key-required)
RFC 9457 problem details. type is a URI with a page describing the problem.
object
Safe to read to a guest.
A machine-readable code on the widget’s routes.
Examples
Venue required
{ "type": "https://developers.kwickblocks.ai/problems/venue-required", "title": "Venue required", "status": 400, "detail": "Please say which venue this is for."}Validation failed
{ "type": "https://developers.kwickblocks.ai/problems/validation-failed", "title": "Validation failed", "status": 400, "detail": "Some of the details weren't valid. Please check them and try again."}Idempotency-Key required
{ "type": "https://developers.kwickblocks.ai/problems/idempotency-key-required", "title": "Idempotency-Key required", "status": 400, "detail": "This request needs an Idempotency-Key header."}Invalid or missing integration key (https://developers.kwickblocks.ai/problems/invalid-key)
RFC 9457 problem details. type is a URI with a page describing the problem.
object
Safe to read to a guest.
A machine-readable code on the widget’s routes.
Examples
Invalid or missing integration key
{ "type": "https://developers.kwickblocks.ai/problems/invalid-key", "title": "Invalid or missing integration key", "status": 401, "detail": "This integration key isn't valid. Ask the venue's admin for a new one."}Capability not granted (https://developers.kwickblocks.ai/problems/capability-missing)
RFC 9457 problem details. type is a URI with a page describing the problem.
object
Safe to read to a guest.
A machine-readable code on the widget’s routes.
Examples
Capability not granted
{ "type": "https://developers.kwickblocks.ai/problems/capability-missing", "title": "Capability not granted", "status": 403, "detail": "This integration key isn't allowed to do that. Ask the venue's admin to add the capability."}Venue not found (https://developers.kwickblocks.ai/problems/venue-not-found)
RFC 9457 problem details. type is a URI with a page describing the problem.
object
Safe to read to a guest.
A machine-readable code on the widget’s routes.
Examples
Venue not found
{ "type": "https://developers.kwickblocks.ai/problems/venue-not-found", "title": "Venue not found", "status": 404, "detail": "I couldn't find that venue."}Idempotency-Key conflict (https://developers.kwickblocks.ai/problems/idempotency-conflict)
RFC 9457 problem details. type is a URI with a page describing the problem.
object
Safe to read to a guest.
A machine-readable code on the widget’s routes.
Examples
Idempotency-Key conflict
{ "type": "https://developers.kwickblocks.ai/problems/idempotency-conflict", "title": "Idempotency-Key conflict", "status": 409, "detail": "That Idempotency-Key was already used for a different request."}Too many requests (https://developers.kwickblocks.ai/problems/rate-limited)
RFC 9457 problem details. type is a URI with a page describing the problem.
object
Safe to read to a guest.
A machine-readable code on the widget’s routes.
Examples
Too many requests
{ "type": "https://developers.kwickblocks.ai/problems/rate-limited", "title": "Too many requests", "status": 429, "detail": "There have been too many requests. Please try again in a minute."}