Sideloading related records

Sometimes you need data from two different APIs. For example, suppose you want to list the authors of help center articles. The records returned by the articles API identify authors only by their Zendesk Support user id, not by their actual names:

{
  "articles": [
    {
      "author_id": 3465,
      ...
    },
    ...
  ]
}

The articles API doesn't return user names, but the users API certainly does. One option might be to call the users API for each article in your results set. This involves hitting the users API repeatedly. Not very efficient.

To avoid unneccesary API calls, you can sideload one set of records with another. Sideloading lets you get both sets of records in a single request. For example, to sideload users, add the include=users URL parameter to the articles endpoint:

curl https://{subdomain}.zendesk.com/api/v2/help_center/fr/articles.json?include=users \
  -v -u {email_address}/token:{api_token}

Where previously the API returned a list of articles, the API now also returns a list of users specified in the articles:

{
  "articles": [
    {
      "author_id": 3465,
      ...
    },
    ...
  ],
  "users": [
    {
      'id': 3465,
      'name': 'Bob Bobberson',
      ...
    }
  ]
}

Critically, the API doesn't get all the users in your Zendesk Support instance. It gets only the users specified in the list of articles. So listing the articles' authors becomes a simple matter of listing the names of the sideloaded users. Example:

url = '.../api/v2/help_center/fr/articles.json?include=users'
response = session.get(url)
data = response.json()
for user in data['users']:
    print(user['name'])

Sideloaded records include only a subset of the resource's properties. For example, the sideloaded records in the example above only include the id , name , and photo user properties. Run the request in curl to learn the included properties of sideloaded records.

The articles API lets you sideload users, sections, categories, and translations. See the API docs for the specific resources you can sideload with other APIs, if any.

For a tutorial that covers sideloading along the way, see List the followers of a KB section .