Expanding Responses

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only. You can expand responses in two ways.

In many cases, an object contains the ID of a related object in its response properties. For example, a CustomerMembership has an associated Membership ID. You can expand these objects in line with the expand request parameter. The Expandable label in this documentation indicates fields that you can expand into objects.

Some available fields aren’t included in the responses by default, are are labelled as Deferred fields in this documentation. For example, the SMSAccount object on a Customer is deferred because most use cases do not require it. You can request these fields as an expanded response by using the expand request parameter.

You can expand recursively by specifying nested fields after a dot (.). For example, requesting event.instructors when fetching attendances expands the event ID property into a full Event object, then expands the instructors property on that event into an array of full Instructor objects.

You can use the expand parameter on any endpoint that returns expandable fields, including list, create, and update endpoints.

Expansions have a maximum depth of four levels. Performing deep expansions on numerous list requests will result in slower processing times.

You can expand multiple objects at the same time by identifying multiple items in the expand array, e.g. GET /api/v2/attendances?expand=event,customer.