Hold a time

POST

/public/v1/holds

curl --request POST \
  --url https://example.kwickbooking.com/public/v1/holds \
  --header 'Content-Type: application/json' \
  --header 'X-KB-Publishable-Key: <X-KB-Publishable-Key>' \
  --data '{ "venueId": "01920000-0000-7000-8000-000000000001", "areaId": "01920000-0000-7000-8000-000000000009", "date": "2026-10-16", "slotStart": "19:00", "partySize": 2 }'

• Your deployment

Holds a time for a few minutes while the guest enters their details. Send an Idempotency-Key header.

Authorizations

• PublishableKey

Request Body^required

Media typeapplication/json

Request to place a transient capacity hold ahead of a booking.

object

venueId

required

string format: uuid

areaId

required

string format: uuid

date

required

string format: date

slotStart

required

string format: time

partySize

required

integer format: int32

Example

{
  "venueId": "01920000-0000-7000-8000-000000000001",
  "areaId": "01920000-0000-7000-8000-000000000009",
  "date": "2026-10-16",
  "slotStart": "19:00",
  "partySize": 2
}

Responses

201

Created

Media typeapplication/json

A placed hold with its expiry (the widget shows the countdown).

object

holdId

required

string format: uuid

expiresAt

required

string format: date-time

Example

{
  "holdId": "01920000-0000-7000-8000-000000000010",
  "expiresAt": "2026-10-12T09:15:00+00:00"
}

400

Validation failed (https://developers.kwickblocks.ai/problems/validation-failed); Idempotency-Key required (https://developers.kwickblocks.ai/problems/idempotency-key-required)

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

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

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

404

Not found (https://developers.kwickblocks.ai/problems/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

Examplenot-found

Not found

{
  "type": "https://developers.kwickblocks.ai/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "I couldn't find that."
}

409

Idempotency-Key conflict (https://developers.kwickblocks.ai/problems/idempotency-conflict); No availability (https://developers.kwickblocks.ai/problems/no-availability)

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

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

No availability

{
  "type": "https://developers.kwickblocks.ai/problems/no-availability",
  "title": "No availability",
  "status": 409,
  "detail": "That time has just gone. Try another time."
}

429

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

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

Examplerate-limited

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