---
title: "Expanding Responses"
description: "Retrieve expanded nested objects in API responses using the expand parameter to reduce additional API calls."
url: "https://help.oncehub.com/developers/overview/expanding-responses"
---

By default, objects embedded in other objects are referenced by their object ID. For example, a booking contains a reference to the Booking Calendar:

```json
{
  "object": "booking",
  "id": "BKNG-J4FR05BKEWEX",
  // ...
  "booking_calendar": "BKC-8DJNDNL86G"
}
```

You can ask to *expand* the `booking_calendar` object by passing an `expand` query parameter to the API:

```http
GET /bookings/BKNG-J4FR05BKEWEX?expand=booking_calendar
```

And the API will return the *expanded* object:

```json
{
  "object": "booking",
  "id": "BKNG-J4FR05BKEWEX",
  // ...
  "booking_calendar": {
    "id": "BKC-8DJNDNL86G",
    "object": "booking_calendar",
    "name": "Andrea Hartie",
    "label": "AndreaHartie",
    "url": "https://go.oncehub.com/andreahartie",
    "active": true
  }
}
```

Note

Expandable properties are listed in this API documentation as *expandable*.

## Multiple Expansions

[Section titled “Multiple Expansions”](#multiple-expansions)

You can pass multiple objects to expand in the response using comma separated values. For example, to expand both `booking_calendar` and `user` you could request:

```http
GET /bookings/BKNG-J4FR05BKEWEX?expand=booking_calendar,user
```

## Expansions in Lists

[Section titled “Expansions in Lists”](#expansions-in-lists)

Expansions on list requests start with the `data` property. For example, you would expand `data.booking_calendar` on a request to list bookings and associated Booking Calendars:

```http
GET /bookings/?expand=data.booking_calendar
```

Expansions on list requests can result in a slower response time.

Since expanding specific data in the response causes additional lookups to multiple data tables, it may result in a slower response time. Only expand data if you have a need for it.

Expansions have a maximum depth of two levels.

To avoid circular calls there is a hard limit to expand to a maximum of two levels.

## Expansions and Webhooks

[Section titled “Expansions and Webhooks”](#expansions-and-webhooks)

Included objects in Webhooks are expanded by default, but additional objects in these payloads cannot be expanded. If you need the fully expanded object, you could trigger a call to the appropriate API upon receiving the webhook.