Skip to content
Kwickblocks Developers

Find a booking

POST
/public/v1/bookings/lookup
curl --request POST \
  --url https://example.kwickbooking.com/public/v1/bookings/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "reference": "4827 1936", "phone": "07911 123456", "venueId": null }'

Finds a booking from its reference and the phone number on it, both in the body. A wrong reference, a wrong phone or a booking at a venue the key doesn’t cover all answer the same not found; repeated failures are throttled. The reply has the booking’s details and the guest’s first name only.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

POST /public/v1/bookings/lookup: the booking’s reference and the phone number on it (both in the body, never the query string).

object
reference
required
string
phone
required
string
venueId
null | string format: uuid
Example
{
  "reference": "4827 1936",
  "phone": "07911 123456",
  "venueId": null
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

The booking found, with a summary to read out.

object
booking
required

A booking as a caller who proved reference and phone may see it: its own details and the guest’s first name, nothing else about the guest.

object
reference
required
string
venueId
required
string format: uuid
venueName
required
string
date
required
string
time
required
string
partySize
required
integer format: int32
bookingType
required
string
state
required
string
guestFirstName
required
string
deposit
required

A booking’s deposit: whether one applies, how much, and none, awaiting_payment or paid.

object
required
required
boolean
amountPence
required
integer format: int32
amountDisplay
required
null | string
status
required
string
expectedArrival
required
null | string
summary
required
string
Example
{
  "booking": {
    "reference": "48271936",
    "venueId": "01920000-0000-7000-8000-000000000001",
    "venueName": "Soho",
    "date": "2026-10-16",
    "time": "20:00",
    "partySize": 4,
    "bookingType": "Table booking",
    "state": "confirmed",
    "guestFirstName": "Sam",
    "deposit": {
      "required": false,
      "amountPence": 0,
      "amountDisplay": null,
      "status": "none"
    },
    "expectedArrival": null
  },
  "summary": "Found Sam's booking at Soho: Fri 16/10 at 20:00 for 4."
}

400

Section titled “400”

Validation failed (https://developers.kwickblocks.ai/problems/validation-failed)

Media typeapplication/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object
type
required
string format: uri
title
required
string
status
required
integer format: int32
detail
required

Safe to read to a guest.

string
instance
string
traceId
string
code

A machine-readable code on the widget’s routes.

string
Examples
Examplevalidation-failed

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."
}

401

Section titled “401”

Invalid or missing integration key (https://developers.kwickblocks.ai/problems/invalid-key)

Media typeapplication/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object
type
required
string format: uri
title
required
string
status
required
integer format: int32
detail
required

Safe to read to a guest.

string
instance
string
traceId
string
code

A machine-readable code on the widget’s routes.

string
Examples
Exampleinvalid-key

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."
}

403

Section titled “403”

Capability not granted (https://developers.kwickblocks.ai/problems/capability-missing)

Media typeapplication/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object
type
required
string format: uri
title
required
string
status
required
integer format: int32
detail
required

Safe to read to a guest.

string
instance
string
traceId
string
code

A machine-readable code on the widget’s routes.

string
Examples
Examplecapability-missing

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."
}

404

Section titled “404”

Booking not found (https://developers.kwickblocks.ai/problems/booking-not-found)

Media typeapplication/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object
type
required
string format: uri
title
required
string
status
required
integer format: int32
detail
required

Safe to read to a guest.

string
instance
string
traceId
string
code

A machine-readable code on the widget’s routes.

string
Examples
Examplebooking-not-found

Booking not found

{
  "type": "https://developers.kwickblocks.ai/problems/booking-not-found",
  "title": "Booking not found",
  "status": 404,
  "detail": "I couldn't find a booking with that reference and phone number."
}

429

Section titled “429”

Too many requests (https://developers.kwickblocks.ai/problems/rate-limited); Too many attempts (https://developers.kwickblocks.ai/problems/lookup-throttled)

Media typeapplication/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object
type
required
string format: uri
title
required
string
status
required
integer format: int32
detail
required

Safe to read to a guest.

string
instance
string
traceId
string
code

A machine-readable code on the widget’s routes.

string
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."
}