Expanding Responses
Expand responses to get related objects inline.
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.
The expandable label in this documentation indicates ID fields that you can expand into objects. When an object contains the ID of a related object in its response properties, you can expand these objects in line with the expand
request parameter.
For example, when querying Sources, without expanding any fields:
The API will return:
connector_version
field returned the ID of the Connector Version model related to this Source.We can then expand this field, using the expand[]
query parameter:
The API will return:
connector
field, inside the connector_version
field returned the ID of the Connector model related to the Connector Version.Expanding recursively
You can expand recursively by specifying nested fields after a dot (.
). For example, requesting connector.customer
on a transaction expands the payment property into a full Payment object, then expands the customer property on that payment into a full Customer object.
This is an example expanding the connector
field of the connector_version
of a Source, using the expand[]
query parameter:
The API will return:
Maximum expansion depth
Expansions have a maximum depth of four levels.
Methods that support expanding
You can use the expand
parameter on any endpoint that returns expandable fields, including list, details, create, and update endpoints.
Performing deep expansions on numerous list requests might result in slower processing times.
You can expand multiple objects at the same time by identifying multiple items in the expand
array.