Side-Loading

Overview

Side-loading allows you to retrieve related records as part of a single request. For example, normally a request to /tickets.json returns ticket resources with a structure similar to:

{
  "tickets": [
    {
      "requester_id": 7,
      ...
    },
    ...
  ]
}

To fetch the requester's data, you must then make another request to /users/7.json.

Using side-loading, you can fetch a partial user resource along with the ticket in a single request. To make the request, add an include parameter containing a comma-separated list of resources to load. Examples:

.../tickets.json?include=users,groups

.../tickets/1.json?include=users,groups

The response will include a top-level array of associated data under the appropriate resource key.

{
  "tickets": [
    {
      "requester_id": 7,
      ...
    },
    ...
  ],
  "users": [
    {
      "id": 7,
      "name": "Bob Bobberson",
      ...
    }
  ]
}

Special Sideloads

Abilities

A resource may have an additional abilities sideload that describes what the current user can do with the resource. Example:

GET /api/v2/users/me.json?include=abilities

{
  "user": {
    "active": true,
    "alias": null,
    "created_at": "2012-05-08T01:04:47Z",
    ...
  },
  "abilities": [
    {
      "can_edit": true,
      "can_edit_password": true,
      "can_manage_identities_of": true,
      "can_verify_identities": false,
      "url": "http://example.zendesk.com/api/v2/users/11.json",
      "user_id": 11
    }
  ]
}
Comment events

A ticket event stream can have a comment_events sideload that includes the ticket comments. The data returned is embedded in the child_events property rather than in a separate array. For more information, see Sideloading in Incremental Ticket Event Export.

Open Ticket Count

A user can have a open_ticket_count sideload that specifies the total number of open tickets assigned to the user.

GET /api/v2/users/me.json?include=open_ticket_count

{
  "user": {
    "id": 10001,
    "active": true,
    "alias": null,
    "created_at": "2012-05-08T01:04:47Z",
    ...
  },
  "open_ticket_count": {
    "10001": 10
  }
}

For a more information, see Sideloading related records in the Zendesk Help Center.

Supported Endpoints

Resource Available associations
Tickets users, groups, organizations, last_audits, metric_sets, dates, sharing_agreements, comment_count, incident_counts, ticket_forms, metric_events (single ticket), slas (single ticket)
Audits users, organizations, groups, tickets
Requests users, organizations
Users organizations, abilities, roles, identities, groups, open_ticket_count
Groups users
Group Memberships users, groups
Automations app_installation, permissions, usage_1h, usage_24h, usage_7d, usage_30d
Macros app_installation, categories, permissions, usage_1h, usage_24h, usage_7d, usage_30d
Triggers app_installation, permissions, usage_1h, usage_24h, usage_7d, usage_30d
Views app_installation, permissions
Organizations abilities
View Execution / Previewing The following are automatically side-loaded if applicable: group, organization, users
Categories (Help Center) translations
Sections (Help Center) categories, translations
Articles (Help Center) users, sections, categories, translations
Article comments (Help Center) users, articles, translations
Subscriptions (Help Center) users, articles, sections
Votes (Help Center) users, articles, translations