# 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

| Endpoint | Resource |
|  --- | --- |
| `GET /venues` | Venue |
| `GET /venues/{venueId}` | Venue |
| `GET /venues/{compositeId}/availability` | AvailabilityResponse |
| `GET /venues/bookings` | Booking |
| `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

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

JavaScript

```javascript
const params = new URLSearchParams({
  fields: 'id,name,location(lat,lng,city)',
});

const response = await fetch(`${BASE_URL}/venues?${params}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

const { data } = await response.json();
// Each venue: { id, name, location: { lat, lng, city } }
```

Python

```python
response = requests.get(
    f'{BASE_URL}/venues',
    params={'fields': 'id,name,location(lat,lng,city)'},
    headers={'Authorization': f'Bearer {access_token}'},
)
response.raise_for_status()
venues = response.json()['data']
# Each venue: { 'id', 'name', 'location': { 'lat', 'lng', 'city' } }
```

Java

```java
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(BASE_URL + "/venues?fields=id%2Cname%2Clocation(lat%2Clng%2Ccity)"))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

C#

```csharp
var query = HttpUtility.ParseQueryString(string.Empty);
query["fields"] = "id,name,location(lat,lng,city)";

var request = new HttpRequestMessage(HttpMethod.Get,
    $"{BASE_URL}/venues?{query}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
```

**Example response:**


```json
{
  "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)
```

cURL

```bash
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"
```

JavaScript

```javascript
const params = new URLSearchParams({
  date: '2025-08-15',
  partySize: 4,
  fields: 'times(time,duration,type)',
});

const response = await fetch(
  `${BASE_URL}/venues/${compositeId}/availability?${params}`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

const { times } = await response.json();
```

Python

```python
response = requests.get(
    f'{BASE_URL}/venues/{composite_id}/availability',
    params={
        'date': '2025-08-15',
        'partySize': 4,
        'fields': 'times(time,duration,type)',
    },
    headers={'Authorization': f'Bearer {access_token}'},
)
response.raise_for_status()
times = response.json()['times']
```

Java

```java
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(BASE_URL + "/venues/" + compositeId +
        "/availability?date=2025-08-15&partySize=4&fields=times(time%2Cduration%2Ctype)"))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

C#

```csharp
var query = HttpUtility.ParseQueryString(string.Empty);
query["date"] = "2025-08-15";
query["partySize"] = "4";
query["fields"] = "times(time,duration,type)";

var request = new HttpRequestMessage(HttpMethod.Get,
    $"{BASE_URL}/venues/{compositeId}/availability?{query}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
```

### 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))))
```

cURL

```bash
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"
```

JavaScript

```javascript
const params = new URLSearchParams({
  date: '2025-08-15',
  partySize: 4,
  fields: 'times(time,duration,type,product(id,name,spaces(id,spaceName,facilities,capacitySeated,policies(minimumSpend,occasionTypes))))',
});

const response = await fetch(
  `${BASE_URL}/venues/${compositeId}/availability?${params}`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

const { times } = await response.json();
```

Python

```python
response = requests.get(
    f'{BASE_URL}/venues/{composite_id}/availability',
    params={
        'date': '2025-08-15',
        'partySize': 4,
        'fields': 'times(time,duration,type,product(id,name,spaces(id,spaceName,facilities,capacitySeated,policies(minimumSpend,occasionTypes))))',
    },
    headers={'Authorization': f'Bearer {access_token}'},
)
response.raise_for_status()
times = response.json()['times']
```

Java

```java
String fields = "times(time,duration,type,product(id,name,spaces(id,spaceName,facilities,capacitySeated,policies(minimumSpend,occasionTypes))))";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(BASE_URL + "/venues/" + compositeId +
        "/availability?date=2025-08-15&partySize=4&fields=" + URLEncoder.encode(fields, StandardCharsets.UTF_8)))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

C#

```csharp
var query = HttpUtility.ParseQueryString(string.Empty);
query["date"] = "2025-08-15";
query["partySize"] = "4";
query["fields"] = "times(time,duration,type,product(id,name,spaces(id,spaceName,facilities,capacitySeated,policies(minimumSpend,occasionTypes))))";

var request = new HttpRequestMessage(HttpMethod.Get,
    $"{BASE_URL}/venues/{compositeId}/availability?{query}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
```

### 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

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

JavaScript

```javascript
const params = new URLSearchParams({
  fields: 'id,compositeId,date,time,partySize,status,firstName,lastName',
});

const response = await fetch(`${BASE_URL}/venues/bookings?${params}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

const { data } = await response.json();
```

Python

```python
response = requests.get(
    f'{BASE_URL}/venues/bookings',
    params={'fields': 'id,compositeId,date,time,partySize,status,firstName,lastName'},
    headers={'Authorization': f'Bearer {access_token}'},
)
response.raise_for_status()
bookings = response.json()['data']
```

Java

```java
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(BASE_URL +
        "/venues/bookings?fields=id%2CcompositeId%2Cdate%2Ctime%2CpartySize%2Cstatus%2CfirstName%2ClastName"))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

C#

```csharp
var query = HttpUtility.ParseQueryString(string.Empty);
query["fields"] = "id,compositeId,date,time,partySize,status,firstName,lastName";

var request = new HttpRequestMessage(HttpMethod.Get,
    $"{BASE_URL}/venues/bookings?{query}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
```

## Combine with TOON for LLM use cases

Sparse fieldsets reduce what data is returned. Pair them with [`Accept: text/toon`](/resources/toon-format) 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.


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

## Related

- [TOON Format](/resources/toon-format)
- [Booking Management](/getting-started/booking-management)
- [Rate Limiting](/resources/rate-limiting)
- [Bookings API Reference](/apis/production/bookingapi)