This page covers the key domain concepts you need to understand before integrating with the Bookable API.
Bookable is a TMS API gateway — a single API that sits above the table management systems that hospitality operators already use day-to-day.
Operators (restaurants, bars, event venues) manage their tables, capacity, and reservations inside a TMS such as Collins, SevenRooms, or Zonal. As a partner, you onboard those operators into Bookable and supply their TMS credentials once. Bookable then handles all communication with the underlying TMS on your behalf, exposing a single consistent API regardless of how many operators or TMS systems are involved.
Your platform
│
▼
Bookable API ← one integration, two APIs
┌──────────────────────────────┐
│ TMS Gateway API │ ← one-time setup: onboard operators + TMS credentials
│ Bookings API │ ← ongoing: search venues, check availability, create bookings
└──────────────────────────────┘
│
┌───┴──────────────┐
Collins SevenRooms Zonal ← operators use whichever TMS they chooseHow the two APIs work together:
| API | Purpose |
|---|---|
| TMS Gateway API | One-time setup — onboard your operators and store their TMS credentials |
| Bookings API | Day-to-day operations — search venues, check availability, create and manage bookings |
You must complete TMS Gateway setup before venues become visible in the Bookings API. Once an operator is onboarded with active TMS credentials, all of their venues appear automatically in GET /venues.
What this means for your integration:
- You write and maintain one integration, regardless of how many operators or TMS systems you connect to
- Real-time availability is read directly from each operator's TMS
- Booking confirmations and status updates are written back to the TMS in real time
- Composite IDs map your API calls to the correct TMS-native venue and product identifiers
An operator is a hospitality business whose venues you want to make bookable — for example, a restaurant group like "Stonegate" or "Big Table Group". Operators are the companies that own and manage venues; each operator may run dozens of individual venues.
Before any of an operator's venues appear in the Bookings API, you must onboard that operator into Bookable using the TMS Gateway API:
POST /operators
{
"businessName": "Acme Restaurant Group",
"partnerSource": "YourTradingName"
}The partnerSource field identifies your bookings channel within the operator's TMS. If the operator has previously worked with your platform, they may already have a label for your channel — ask them before creating a new one, so booking attribution stays consistent.
Once onboarded, the operator gets a numeric operatorId that you use in all TMS credential calls.
TMS credentials connect an onboarded operator to their table management system. They tell Bookable how to authenticate with that TMS on the operator's behalf — unlocking real-time availability and booking capability for all of that operator's venues.
An operator may hold credentials for more than one TMS (for example, Collins for some venues, SevenRooms for others).
Bookable currently supports three TMS systems:
| TMS | Slug | Auth type | Required fields |
|---|---|---|---|
| Collins | CO | Bearer token | bearer, externalOperatorId |
| SevenRooms | SR | Client credentials | clientId, secretId |
| Zonal | ZO | Basic auth | clientId, secretId |
Add credentials with:
POST /operators/{operatorId}/tms-credentials
{
"tmsSlug": "CO",
"bearer": "eyJ0eXAi...",
"externalOperatorId": "514ada610df690b6770000fd",
"active": true
}Once the credentials are active, the operator's venues are immediately available via GET /venues in the Bookings API.
See the Operator Setup guide for step-by-step instructions and multi-language code examples.
Bookable provides two environments:
| Sandbox | Production | |
|---|---|---|
| Base URL | https://api-sandbox.bookabletech.com | https://api.bookabletech.com |
| Auth URL | https://auth-sandbox.bookabletech.com/oauth/token | https://auth.bookabletech.com/oauth/token |
| Credentials | Sandbox client_id / client_secret | Production client_id / client_secret |
| Data | Test venues with simulated availability | Live operator venues |
| Charges | No real charges | Real transactions |
Sandbox credentials are scoped to the sandbox environment only — they will not work against the production API.
Both sets of credentials are available in the Bookable Portal under your account settings.
Use the sandbox for all development and testing. Switch to production credentials and the production base URL only when you are ready to go live.
A venue represents a single physical location — a restaurant, bar, private dining room, or event space. Each venue is independently managed by an operator.
A venue exposes one or more products: the bookable experiences it offers. A product might be "Bottomless Brunch", "Private Dining Room A", or simply "Table Reservation". Each product has its own availability rules, capacity limits, and pricing.
When you search for venues (GET /venues), the response includes a products array on each venue object. This is where you find the compositeId required for all subsequent calls.
All booking and availability endpoints require a composite ID to identify a specific venue-product combination.
The composite ID is a pipe-delimited string with four parts:
OperatorId|TmsSlug|VenueId|ProductIdExample: 29|CO|275cc44dd2e2496fba44857c9257443a|d99128c546b34b619c4477b712869f2b
Always treat it as an opaque string — do not parse or construct it manually.
Where to find it:
// GET /venues response (truncated)
{
"data": [
{
"name": "The Grand Table",
"products": [
{
"compositeId": "29|CO|275cc44dd2e2496fba44857c9257443a|d99128c546b34b619c4477b712869f2b",
"productName": "Table Reservation"
}
]
}
]
}Use products[].compositeId as the {compositeId} path parameter in all availability and booking endpoints:
GET /venues/{compositeId}/availability
POST /venues/{compositeId}/bookingEach product has an availabilityType that determines how a booking is confirmed:
| Type | Description |
|---|---|
book | Instant confirmation. The booking is confirmed immediately upon creation. |
request | Manual approval required. The booking enters a pending state and must be approved by the venue operator. |
You must pass the correct type in the type field when creating a booking. To find the correct type, check the times array in the availability response and use the type from the slot you want to book:
// GET /venues/{compositeId}/availability response (truncated)
{
"times": [
{ "time": "19:00", "duration": 90, "type": "book" },
{ "time": "19:30", "duration": 90, "type": "request" }
]
}Always use the type from the availability response — do not hardcode it.
| Status | Meaning |
|---|---|
Pending | Request submitted, awaiting operator approval |
Confirmed | Booking accepted — instant (book) or approved (request) |
Cancelled | Booking was cancelled or declined |
A confirmed booking has a unique id (format: OperatorId|TmsSlug|BookingId) and an operatorBookingId (the reference assigned by the venue's TMS). Store both — use id in API calls and operatorBookingId when communicating with guests.