Skip to content
CibusyDevelopers
TREN
Get an API key

Reservations

List reservations

The reservations taken through the API, a page at a time; the open ones soonest first.

GET/public/v1/reservations
Authentication

An API key in the X-Api-Key header

Permission
Can take reservations
Rate limit
About 120 requests a minute per key

Lists the reservations the API took at the venues the key reaches, whichever of the venue's keys took them: one taken with a key that has since been replaced is still listed. A booking the venue took some other way, in the Cibusy app, on its page on cibusy.com or over the phone, is not listed. Each item is the same body GET /reservations/{reservationId} returns.

The order depends on what is asked for. open comes soonest first: the next table to arrive is at the top. closed and all come latest first. Read a page at a time: while nextCursor is not null, ask again with cursor set to it.

Guide: Taking reservations

Parameters

venueIdstring · uuidQuery parameter

Only this venue's reservations. A headquarter's key can name one of its branches; leave it out to list the reservations of every venue the key reaches.

statusstringQuery parameter

Which reservations: open (pending, confirmed or seated, the default), closed (declined, cancelled, completed or a no-show) or all.

Default: Open

Values:OpenClosedAll

cursorintegerQuery parameter

The page to read, counted from 1. Take it from nextCursor of the previous page.

Default: 1

pageSizeintegerQuery parameter

Reservations per page: 1 to 100, 50 by default.

Default: 50

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.

Responses

200

One page of reservations.

400

INVALID_PAGE_NUMBER, INVALID_PAGE_SIZE, or VALIDATION_ERROR for a status that is not one of the three.

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

PUBLIC_API_VENUE_NOT_FOUND: venueId is not a venue this key can reach.

429

The key's budget of about 120 requests 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

One page of the reservations taken through the API.

itemsobject[]

The page's reservations. At most pageSize of them; empty past the last page.

Fields of Reservation
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.

nextCursorintegernullable

The cursor to send for the next page, or null when this is the last. A cursor is a page number, counted from 1.