Skip to content
Last updated

Sparse Fieldsets

By default, Bookable API responses return every field on the resource. Sparse fieldsets let you request only the fields you need, reducing payload size and improving response times — particularly useful for list endpoints where you may only need a few fields per record.

How it works

Add a fields query parameter to any supported GET endpoint. The value is a comma-separated list of top-level field names. To select sub-fields of a nested object, use parentheses.

fields=<field1>,<field2>,<field3(subfield1,subfield2)>

When fields is omitted, the full response is returned — fully backwards compatible.

Supported endpoints

EndpointResource
GET /venuesVenue
GET /venues/{venueId}Venue
GET /venues/{compositeId}/availabilityAvailabilityResponse
GET /venues/bookingsBooking
GET /venues/bookings/{bookingId}Booking

Syntax

Select top-level fields

fields=id,name,location

Select sub-fields of a nested object

Use parentheses to drill into a complex field:

fields=id,name,location(lat,lng,city)

Nest multiple levels deep

Nesting can go multiple levels:

fields=id,name,products(compositeId,productName,availabilityRules(from,to))

Multiple nested objects

Separate nested selections with commas inside parentheses:

fields=id,name,location(lat,lng,city),products(compositeId,productName,category)

Available fields by resource

Venue

Valid top-level fields: id, name, venueGroupName, content, phone_number, website, reservable, location, types, photos, is_active, created_at, updated_at, products, preorders, opening_times

products sub-fields

compositeId, productName, timeInterval, preOrderRequired, preOrderRequiredType, depositRequired, availabilityRules, category, preorders, spaces

products.spaces sub-fields

id, spaceName, description, floorLocation, facilities, capacityStanding, capacitySeated, capacityCabaret, capacityTheatre, capacityBoardroom, capacityClassroom, capacityUShape, capacityBanquet, capacityReception, policies

Each capacity field supports sub-fields: min, max

products.spaces.policies sub-fields

minimumSpend, occasionTypes, under18s, promotedEvents, accessibility, servesFood

AvailabilityResponse

Valid top-level fields: name, deposit, policy, cancellationPolicy, times

times sub-fields

time, duration, type, product

times.product sub-fields

id, name, spaces

times.product.spaces sub-fields

id, spaceName, description, floorLocation, facilities, capacityStanding, capacitySeated, capacityCabaret, capacityTheatre, capacityBoardroom, capacityClassroom, capacityUShape, capacityBanquet, capacityReception, policies

Each capacity field supports sub-fields: min, max

times.product.spaces.policies sub-fields

minimumSpend, occasionTypes, under18s, promotedEvents, accessibility, servesFood

minimumSpend entries are pre-filtered to the requested date and time slot — use them directly without additional client-side filtering.

Booking

Valid top-level fields: id, compositeId, date, time, partySize, status, firstName, lastName, email, phone, venueGroupName, location, duration, productName, notes, createdDate, lastUpdate, preorders, partnerBookingId, operatorBookingId

Examples

Fetch venue list — names and locations only

GET /venues?fields=id,name,location(lat,lng,city)
curl "https://api.bookabletech.com/venues?fields=id,name,location(lat,lng,city)" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response:

{
  "data": [
    {
      "id": "29|X9|275cc44dd2e2496fba44857c9257443a",
      "name": "The Grand Table",
      "location": {
        "lat": 51.5074,
        "lng": -0.1278,
        "city": "London"
      }
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

Check availability — times only

GET /venues/{compositeId}/availability?fields=times(time,duration,type)
COMPOSITE_ID="29|CO|275cc44dd2e2496fba44857c9257443a|d99128c546b34b619c4477b712869f2b"

curl "https://api.bookabletech.com/venues/${COMPOSITE_ID}/availability?date=2025-08-15&partySize=4&fields=times(time,duration,type)" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Check availability — times with space details

GET /venues/{compositeId}/availability?fields=times(time,duration,type,product(id,name,spaces(id,spaceName,facilities,capacitySeated,policies(minimumSpend,occasionTypes))))
COMPOSITE_ID="29|CO|275cc44dd2e2496fba44857c9257443a|d99128c546b34b619c4477b712869f2b"

curl "https://api.bookabletech.com/venues/${COMPOSITE_ID}/availability?date=2025-08-15&partySize=4&fields=times(time,duration,type,product(id,name,spaces(id,spaceName,facilities,capacitySeated,policies(minimumSpend,occasionTypes))))" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Fetch bookings — status dashboard

Only request what you need to power a booking list UI:

GET /venues/bookings?fields=id,compositeId,date,time,partySize,status,firstName,lastName
curl "https://api.bookabletech.com/venues/bookings?fields=id,compositeId,date,time,partySize,status,firstName,lastName" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Combine with TOON for LLM use cases

Sparse fieldsets reduce what data is returned. Pair them with Accept: text/toon to also strip JSON syntactic noise from the result. Together they can cut token consumption by 60–75% compared to a default JSON response — directly reducing OpenAI and Claude API costs when feeding Bookings API data into an LLM.

GET /venues?fields=id,name,location(city),products(compositeId,productName)
Accept: text/toon
Previous page
Next page