Expanding Responses

How it works

The Treevox API is organized into resources represented by objects with state, configuration, and contextual properties. These objects all have unique IDs that you can use to retrieve, update, and delete them. The API also uses these IDs to link related objects together

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.

In many cases, an object contains the ID of a related object in its response properties. For example, a Contacts may have an associated assignedTo ID. Those objects can be expanded inline with the expand request parameter.

Example - Request

curl --location -g --request GET 'https://api.treevox.com/v1/contacts?expand[]=assignedTo' \
--header 'Content-Type: application/json' \
--header 'Accept-Encoding: gzip' \
--header 'x-api-key: {your_api_key}

Example response

{
  "data": [
    {
      ...,
      "assignedToId": 1,
      "assignedTo": {
        "id": 1,
        "name": "Name",
        "surname": "Surname",
        "createdAt": "2020-12-12T18:46:43.291Z",
        "updatedAt": "2021-06-18T00:57:17.481Z"
      },
      ...
    },
    ...
  ],
  "pagination": {
    ...
  }
}

In the example answer you can see that a new property called assignedTo was added which contains the related object.

You can expand multiple objects at once by identifying multiple items in the expand array.

curl --location -g --request GET 'https://api.treevox.com/v1/contacts?expand[]=assignedTo&expand[]=organization' \
--header 'Content-Type: application/json' \
--header 'Accept-Encoding: gzip' \
--header 'x-api-key: {your_api_key}