Expanding Resources

Several objects support the retrieval of additional information through an expanded response by utilizing the expand request parameter. This parameter is applicable to most API requests and influences the response of the corresponding request.

In numerous scenarios, an object includes the ID of a correlated object within its response properties. For instance, a Booking has an associated Booker ID. You have the option to expand the Booker object using the expand request parameter. The expandable label in this documentation specifies ID fields that can be expanded into objects.

Example for GET /private/bookings/{id}

{
    "data": {
        "id": "ceba4275-479b-41a9-8a69-a4446ab693b9",
        "reference": "2023-3494",
        "starts_at": "2024-07-15 14:00:00",
        "ends_at": "2024-07-22 13:00:00",
        "status": "pending",
        "booker_id": "044fdd7d-22f8-4423-bac7-bb8fda345305",
        ...
    }
}

In Booking response you can always see booker_id. However, when you need more details about the Booker you can just expand by adding expand[]=booker to request query string.

Example for GET /private/bookings/{id}?expand[]=booker

{
    "data": {
        "id": "64938537-5947-40e8-8185-1042f16bf479",
        "reference": "2023-2494",
        "starts_at": "2024-07-15 14:00:00",
        "ends_at": "2024-07-22 13:00:00",
        "status": "pending",
        "booker_id": "ba03075f-ce2b-4003-ae36-4ed54d1f76a3",
        "booker": {
            "person": {
                "id": "ba03075f-ce2b-4003-ae36-4ed54d1f76a3",
                "first_name": "Henry",
                "last_name": "Smith",
                "initials": "HS",
                "gender": "male",
                "birth_date": null,
                "email": "[email protected]",
                ...
            },
            "booking_related_data": {
                "tax_number": 2234567895,
                "company_name": "Bookinglayer",
                ...
            }
        }
    }
}

We never expand relations by default. Also one/many-to-many relations don't have arrays of foreign keys (ID's) in the default response. You have to explicitly expand then when it's needed. Example Locations in Booking resource.

{
    "data": {
        "id": "ceba4275-479b-41a9-8a69-a4446ab693b9",
        "reference": "2023-3494",
        "reseller_reference": null,
        "is_connect": false,
        "starts_at": "2024-07-15 14:00:00",
        "ends_at": "2024-07-22 13:00:00",
        "status": "pending",
        ...
        "locations": [
            {
                "id": 1234,
                "backoffice_title": "Portugal",
                "title": "Portugal Algarve",
                "description": "...",
                "abbreviation": "POAL",
                "address": null,
                "zip_code": null,
                "city": null,
                "latitude": null,
                "longitude": null,
                "metadata": null,
                "deleted_at": null,
                "created_at": "2019-11-29T13:59:20+00:00",
                "updated_at": "2019-11-29T13:59:20+00:00",
            }
        ],
        ...
        "created_at": "2023-10-24T10:58:11+00:00",
        "updated_at": "2023-10-24T10:58:21+00:00"
    }
}

Recursive expansion is achieved by specifying nested fields after a dot (.) in the request. For instance, if you request invoices.payments on a Booking, it expands the Booking property with invoices lists and payments for those invoices.

You can use the expand parameter on any endpoint that returns expandable fields, including list, fetch single, create and update endpoints. Performing deep expansions on numerous list requests might result in slower processing times. Expansions have a maximum depth of three levels. You can expand multiple objects at the same time.