Expansion

By default, many API endpoints will only return first-order non-collection properties of a resource. These properties can be “expanded” by specifying valid expansion properties or sections in the $expand query parameter. This technique is used in both “list” endpoints and “get” endpoints.

If a collection property is not specified in an $expand parameter, the value of that property will be null. If a collection property is specified in an $expand parameter but that property has no values, that property will be an empty array.

📘

Look out for the $expand parameter in documentation — it is sometimes used for non-collection properties, too!

For example, consider a Person object that has name properties and collections of addresses, of emails, and of phone numbers.

GET /people/432135

Returns the first-order properties (names) and null values for addresses, emails, and phones.

{
  "firstName": "Jim",
  "lastName": "Gordon",
  "addresses": null,
  "emails": null,
  "phones": null
}

Emails and phones can be requested by specifying emails and phones in the query string:

GET /v4/people/432135?$expand=emails,phones

Returns the first-order properties (names), populated emails and phones (even though the record has no phone numbers), and null value for addresses:

{
  "firstName": "Jim",
  "lastName": "Gordon",
  "addresses": null,
  "emails": [
    {
      "email": "[email protected]",
      "type": "Work",
      "isPreferred": false
    },
    {
      "email": "[email protected]",
      "type": "Home",
      "isPreferred": true
    }
  ],
  "phones": []
}

Sending an $expand parameter to an endpoint that does not expand parameters will yield a 400 Bad Request error response:

{
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "text": "There are no valid expand sections for this endpoint, therefore '$expand' must be null",
      "properties": [
        "$expand"
      ]
    }
  ]
}

Sending an invalid $expand parameter to an endpoint also yields a 400 Bad Request error response. The supported properties are included in the hint of the error:

{
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "text": "'addresses' is not a valid argument for the '$expand' parameter",
      "properties": [
        "$expand"
      ],
      "hint": "The only valid expand section is: 'phones'"
    }
  ]
}