Skip to content

Listings API V1 (1.0.0)

Overview

The Listings API V1 is a venue-aggregated discovery interface.

The response root carries meta and listings[]. Each entry in listings[] is a ListingGroup — one per operator (venue-group / chain), carrying a groupName and an items[] array.

Each item represents a single venue (or a standalone event when no venue is known): it carries the venue name, a location, and a capabilities[] array. Each entry in capabilities[] is a Listing with exactly one capability (table_reservation or event_ticket), and carries its own photos[]. A venue that also hosts a ticketed event therefore yields a single item with two capabilities — one for the venue, one for the event.

All bookable units (venue products, event ticket types, future capability types) are unified under a single bookableProducts[] array. Every entry is a single Bookable shape; capability-specific fields are nullable and the parent Listing's capability sets the context.

Temporal information (venue opening hours, event occurrences, blackout dates) is unified under a single availabilityOccurrence[] field of CalendarRules. Both capabilities use the same shape.

Pre-order assets (packages, menus) are unified under a single preorders container — applicable to either capability when the listing supports pre-orders.

ID formats — two distinct identifiers, both CompositeId-encoded

Listing.id (venue or event, as returned in /v1/listings) is 3 segments: {VenueGroupId}|{RmsSlug}|{ResourceId}. For a hybrid entity the event-side row uses the EventExt's CompositeId (different RmsSlug + ResourceId) so the two rows are unambiguous.

Bookable.compositeId (a specific bookable product/ticket type — used in bookableProducts[], and as the compositeId in /v1/availabilities and /v1/orders) is 4 segments: {VenueGroupId}|{RmsSlug}|{ResourceId}|{AdditionalId}. These are two different identifiers for two different things, not two interchangeable formats for the same one — a Listing.id never appears where a Bookable.compositeId is expected, or vice versa.

Download OpenAPI description
ListingsApiV1.json
ListingsApiV1.yaml
Overview
URL
https://www.bookabletech.com
Bookable
hello@bookabletech.com
Languages
Servers
Live
https://api.bookabletech.com
Sandbox
https://api-sandbox.bookabletech.com

Listings

Discover and retrieve bookable listings

Operations

Retrieve the full bookable catalogue (paginated, venue-aggregated)

Request

Returns the entire bookable catalogue available to the caller, paginated and venue-aggregated. Results are grouped by operator (ListingGroup); each group carries its venues (ListingItem), and each venue carries one Listing per capability it offers (table_reservation, event_ticket).

A venue that also hosts a ticketed event therefore appears once, with two entries in its capabilities[] — one per capability. Optional query filters (capability, name, location, features, date, …) narrow the catalogue; with no filters the whole catalogue is returned page by page.

Security
Live(Required scopes:
listing:read
) or Sandbox(Required scopes:
listing:read
)
Query
capabilitystring

Restrict results to a single capability. Venues are still returned aggregated; only their matching capability entries are included.

Enum"table_reservation""event_ticket"
Example: capability=table_reservation
venueNamestring[ 2 .. 100 ] characters

Filter by listing name — partial, case-insensitive match.

Example: venueName=dishoom
operatorNamestring[ 2 .. 100 ] characters

Filter by operator (venue-group / chain) name.

Example: operatorName=stonegate
citystring[ 2 .. 100 ] characters
Example: city=london
areastring[ 2 .. 100 ] characters
Example: area=shoreditch
featuresArray of strings[ 1 .. 10 ] items

Filter by type / feature slugs (matched against types). Comma-separated list.

Example: features=dog_friendly,live_music
datestring(date)

Filter listings that have availability on a specific date (YYYY-MM-DD).

Example: date=2026-06-15
fieldsstring

Field selection using Google Fields syntax. Comma-separated list of top-level Listing fields to include. When omitted, all fields are returned.

Example: fields=id,name,capability,location(lat,lng,city),bookableProducts(compositeId,name)
pageNumberinteger>= 1
Default 1
pageSizeinteger[ 1 .. 100 ]
Default 20
sortBystring
Default "default"
Enum"default""name""city""area""relevance"
sortDirectionstring
Default "ASC"
Enum"ASC""DESC"
Headers
X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents — identifies the partner on whose behalf the request is made.

Example: bottomlessbrunch.com
curl -i -X GET \
  'https://api.bookabletech.com/v1/listings?capability=table_reservation&venueName=dishoom&operatorName=stonegate&city=london&area=shoreditch&features=dog_friendly%2Clive_music&date=2026-06-15&fields=id%2Cname%2Ccapability%2Clocation%28lat%2Clng%2Ccity%29%2CbookableProducts%28compositeId%2Cname%29&pageNumber=1&pageSize=20&sortBy=default&sortDirection=ASC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com'

Responses

Paginated list of listings.

Headers
X-Correlation-IDstring
X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200
X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150
X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200
Body
metaobject
listingsArray of objects(ListingGroup)
Response
{
  "meta": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1
  },
  "listings": [
    { … }
  ]
}

Check availability for multiple bookable products in one call

Request

Batch availability check. Modelled as a command (POST), not a search.

The request carries root-level date, quantity and optional time, plus a bookableProducts[] list. Each entry has a required compositeId and may override date, quantity and time. When an entry omits any of those, the root-level value is used.

quantity carries the count for either capability, same as in POST /v1/orders — number of covers for a table reservation, number of tickets for an event-ticket line.

Every entry must end up with date and quantity resolved (either from the entry or the root). time is optional — event capabilities are queried by date alone; for table reservations it narrows the slot when supplied. An entry that cannot resolve date and quantity is reported as an error result and does not block the others.

Searches run independently: a failure on one compositeId yields an error on that result only — all other results are returned normally. The response carries one AvailabilityResult per requested compositeId, preserving request order.

There is no 404 response: an unknown/nonexistent compositeId is not a request-level failure — it's reported as an error on that entry's AvailabilityResult, same as any other per-entry failure (e.g. unresolved date/quantity), never as an HTTP-level not-found for the whole call.

Security
Live(Required scopes:
listing:read
) or Sandbox(Required scopes:
listing:read
)
Headers
X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents — identifies the partner on whose behalf the request is made.

Example: bottomlessbrunch.com
Bodyapplication/jsonrequired
datestring or null(date)

Default booking date (YYYY-MM-DD), inherited by entries that omit it.

Example: "2026-06-15"
quantityinteger or null>= 1

Default quantity, inherited by entries that omit it — same field as OrderItem.quantity. For a table_reservation bookable, quantity is the number of people (covers); for an event_ticket bookable, quantity is the number of tickets.

Example: 4
timestring or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$

Optional default start time (HH:mm), inherited by entries that omit it.

Example: "19:00"
bookableProductsArray of objects(AvailabilityProductRequest)[ 1 .. 100 ] itemsrequired

Bookable products to check. One result is returned per entry.

bookableProducts[].​compositeIdstringrequired

CompositeId of the bookable product to check.

Example: "29|CS|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"
bookableProducts[].​datestring or null(date)

Overrides the root date for this entry.

Example: "2026-06-15"
bookableProducts[].​quantityinteger or null>= 1

Overrides the root quantity for this entry — number of people for a table_reservation bookable, number of tickets for an event_ticket bookable.

Example: 2
bookableProducts[].​timestring or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$

Overrides the root time for this entry.

Example: "20:00"
curl -i -X POST \
  https://api.bookabletech.com/v1/availabilities \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com' \
  -d '{
    "date": "2026-06-15",
    "quantity": 4,
    "time": "19:00",
    "bookableProducts": [
      {
        "compositeId": "29|CS|275cc44dd2e2496fba44857c9257443a|prod1"
      },
      {
        "compositeId": "29|CS|275cc44dd2e2496fba44857c9257443a|prod2",
        "quantity": 2,
        "time": "20:00"
      },
      {
        "compositeId": "29|CS|999|prod3"
      }
    ]
  }'

Responses

One result per requested compositeId. Each result carries either availability (success) or error (failure); never both.

Headers
X-Correlation-IDstring
X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200
X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150
X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200
Bodyapplication/json
resultsArray of objects(AvailabilityResult)required

One result per requested compositeId, in request order.

results[].​compositeIdstringrequired

The compositeId this result refers to.

Example: "29|CS|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"
results[].​availabilityobject(Availability)

Availability for a single bookable product. Mirrors the BookingApi AvailabilityResponse.

results[].​errorobject(ServerError)
Response
application/json
{
  "results": [
    { … },
    { … },
    { … }
  ]
}

Orders

Create and manage orders

Operations