Reservations

Take a reservation

Send in a booking your site took. It lands on the venue's reservation list; whether it is confirmed at once is the venue's own setting.

POST/public/v1/venues/{venueId}/reservations

Authentication: An API key in the X-Api-Key header
Permission: Can take reservations
Rate limit: About 30 requests a minute per key

Warning: There is no sandbox. A reservation taken with a real key is a real booking on a real venue's list, and its staff are told. Develop against a venue you run, and cancel what you make.

Send the booking your site took. The answer is 201 Created with a Location header pointing at GET /reservations/{reservationId}. The booking lands where every other one does: on the venue's reservation list at the till and in the staff app, with the notification a guest's own booking raises. More in Taking reservations.

Take the time from the availability call. startsAt is an instant in UTC; send the startsAt of a slot from the bookable times. guests is 1 to 20, the guest's name is at most 100 characters, the phone number 30 and the note 250.

Whether it is confirmed is the venue's setting. At a venue that confirms bookings as they are made the answer is Confirmed; otherwise it is Pending until somebody at the venue accepts or declines it. A request the venue has not answered by the time it was for is cancelled by the System. confirmsAutomatically in the availability answer says which to expect.

You tell the guest. Cibusy sends no text message about a reservation taken through the API: your site took the booking, and it is your site the guest expects to hear from. Give the guest the pageUrl of the answer, or its code: it is what the venue checks them in with at the door.

Sending it twice is safe, and needs no Idempotency-Key. A guest cannot sit at two tables at once, so a second request for the same phone number at the same venue for the same moment, while the first booking still stands, is the same booking. You get the one the first call made, as the venue has it now, with status 200 OK, and the venue is not told a second time. If your request times out, send it again unchanged. A repeat is answered before the venue's rules are looked at again, since the booking already exists.

The venue's booking rules decide whether the time can be taken, the same ones its own booking page holds a guest to: the venue takes bookings (RESERVATIONS_DISABLED), at most 20 guests (TOO_MANY_GUESTS), a time in the future (INVALID_RESERVATION_DATE), at least 30 minutes away (RESERVATION_TOO_SOON), at most 60 days ahead (RESERVATION_TOO_FAR) and one the venue seats at (RESERVATION_TIME_UNAVAILABLE). A time taken from the availability answer passes all of them. The venue also needs an active subscription (PUBLIC_API_RESERVATIONS_UNAVAILABLE). Where an error names a part of the request, validationErrors says which, by path (customer.phone).

Guide: Taking reservations

Parameters

venueIdstring · uuidPath parameterrequired

The venue, one of the ids GET /venues lists.

Accept-LanguagestringHeader

The language of userMessage in an error: tr (the default), en, de, fr, it, es, ar or ru. The first language in the header decides, without its region (en-US reads as en) and without weighing q values; a language Cibusy does not offer is answered in Turkish. It does not choose the language of a menu: that is lang on the menu call.

Request body

A booking a venue's site took and sends in. The venue's own booking rules decide whether it can be taken: GET /venues/{venueId}/reservation-availability lists the times that will be accepted.

startsAtstring · date-timenullable

When the table is for, as an instant in UTC. Take it from a slot's startsAt in the availability answer. Required.

guestsintegernullable

How many people are coming: 1 to 20. A larger party is booked by calling the venue. Required.

customerobjectnullable

Who the table is for. Required.

Fields of Guest details

namestringnullable

The guest's name, at most 100 characters. Required.

phonestringnullable

The guest's phone number, in international form or the way it is written locally (+905321112233, 0532 111 22 33). At most 30 characters. Required: it is how the venue reaches the guest, and what tells a repeated request from a second booking.

notestringnullable

A note for the venue, at most 250 characters.

Responses

200

A repeat: the reservation the same phone number, venue and time already made, as the venue has it now.

201

The reservation was taken. Location points at it; status says whether it is confirmed (Confirmed) or waiting for the venue (Pending).

Location

Where the reservation can be read: /public/v1/reservations/{reservationId}.

400

PUBLIC_API_RESERVATION_INVALID, TOO_MANY_GUESTS or INVALID_RESERVATION_DATE.

401

The X-Api-Key header is missing (PUBLIC_API_KEY_MISSING), or the key is invalid or has been revoked (PUBLIC_API_KEY_INVALID).

403

PUBLIC_API_SCOPE_MISSING: the key was not made with the "Can take reservations" permission.

404

The venue does not exist, or this key cannot reach it (PUBLIC_API_VENUE_NOT_FOUND).

409

PUBLIC_API_RESERVATIONS_UNAVAILABLE, RESERVATIONS_DISABLED, RESERVATION_TOO_SOON, RESERVATION_TOO_FAR or RESERVATION_TIME_UNAVAILABLE.

429

The key's budget of about 30 orders, reservations and tests a minute is spent; wait Retry-After seconds.

Retry-After

Seconds to wait. The next one-minute window opens within it.

The `data` of a successful answer

A reservation taken through the API, as the venue has it right now. The same body GET /reservations/{reservationId} returns and the webhook's reservation.updated event carries.

idstring · uuid

The reservation's id. Use it with GET /reservations/{reservationId}.

venueIdstring · uuid

The venue the table is booked at.

statusstring

Where the reservation has got to, worked out on every read, so the list, a read of one reservation and a webhook event cannot say different things about the same booking.

Pending: The venue has not answered yet. A venue that confirms bookings as they are made never shows this.
Confirmed: The venue accepted it, or confirms bookings as they are made. The table is expected.
Declined: The venue declined the request.
Cancelled: It was called off. `cancelledBy` says by whom.
Seated: The guest has arrived and was checked in at the door.
Completed: The visit is over.
NoShow: The venue accepted it and nobody came.

startsAtstring · date-time

When the table is for, as an instant in UTC.

guestsinteger

How many people are coming.

customerobject

Who the table is for, as the venue has it.

Fields of Reservation guest

namestringnullable

The guest's name.

phonestringnullable

The guest's phone number, in international form.

notestringnullable

The note the reservation was made with. null when there was none.

codestringnullable

The code the venue checks the guest in with at the door: eight characters the guest can read out, or show as the QR on pageUrl. Whoever holds it can see and cancel the booking, so give it to the guest and to nobody else.

pageUrlstringnullable

The reservation's own page on cibusy.com, which shows the booking and, once it is confirmed, the QR the venue scans at the door. Link to it or send it to the guest. null for a venue with no public address.

canCancelboolean

Whether the reservation can still be cancelled through the API: it stands, the guest has not been checked in and its time has not come.

checkedInAtstring · date-timenullable

When the guest was checked in at the door, in UTC. null until then.

cancelledAtstring · date-timenullable

When the reservation was called off, in UTC. null unless status is Cancelled.

cancelledBystringnullable

Who called it off. null unless status is Cancelled.

Customer: The guest: through this API, on the reservation's own page, or in the Cibusy app.
Venue: The venue.
System: Cibusy, when the venue had not answered a request by the time it was for.

cancellationReasonstringnullable

What was given as the reason for calling it off, in the words of whoever gave it. null unless status is Cancelled.

createdAtstring · date-time

When the reservation was made, in UTC.

Request sample

curl -X POST "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/reservations" \
  -H "X-Api-Key: $CIBUSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startsAt": "2026-10-09T17:00:00.000Z",
    "guests": 4,
    "customer": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233"
    },
    "note": "Mümkünse cam kenarı bir masa."
  }'

Response sample

201 Created

{
  "success": true,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "data": {
    "id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
    "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "Pending",
    "startsAt": "2026-10-09T17:00:00.000Z",
    "guests": 4,
    "customer": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233"
    },
    "note": "Mümkünse cam kenarı bir masa.",
    "code": "K7M2Q9XA",
    "pageUrl": "https://cibusy.com/modakofte/reservation/K7M2Q9XA",
    "canCancel": true,
    "checkedInAt": null,
    "cancelledAt": null,
    "cancelledBy": null,
    "cancellationReason": null,
    "createdAt": "2026-10-01T09:30:00.000Z"
  },
  "message": "Operation completed successfully"
}

Error sample

400 Bad Request

{
  "success": false,
  "userMessage": "The reservation request is not valid. Check the time, the number of guests and the customer details.",
  "developerMessage": "The reservation request is not valid. guests: At least 1. customer.phone: Not a phone number.",
  "errorCode": "PUBLIC_API_RESERVATION_INVALID",
  "validationErrors": [
    {
      "field": "guests",
      "message": "At least 1.",
      "attemptedValue": null
    },
    {
      "field": "customer.phone",
      "message": "Not a phone number.",
      "attemptedValue": null
    }
  ],
  "details": null,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null
}