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 more information, see Sideloading related records.

Searches

Search supports sideloads. However, you must specify the type of records searched in the include query parameter to sideload data related to that record type. Specify the type and sideload using the following syntax:

include={type}({sideload})

For example, the following request searches for a user and specifies the type users to sideload the user's identities:

/api/v2/search.json?query=email:jdoe@example.com&include=users(identities)‚Äč

The following request searches for tickets and specifies the type tickets to sideload the tickets' user and SLA data:

api/v2/search.json?query=type:ticket%20billing&include=tickets(users,slas)

See the table in Supported Endpoints for the supported sideloads for different record types.

Supported Endpoints

The following Support API resources support side-loaded records:

Support API resourceSide-loaded records
Ticketsbrands, custom_statuses, users, groups, organizations, last_audits, metric_sets, dates, sharing_agreements, comment_count, incident_counts, ticket_forms, metric_events (single ticket), slas (single ticket)
Ticket Fieldsusers
Ticket Formsticket_fields
Auditsusers, organizations, groups, tickets
Requestsusers, organizations
Usersorganizations, abilities, roles, identities, groups, open_ticket_count
Groupsusers
Group Membershipsusers, groups
Automationsapp_installation, permissions, usage_1h, usage_24h, usage_7d, usage_30d
Macrosapp_installation, categories, permissions, usage_1h, usage_24h, usage_7d, usage_30d
Triggersapp_installation, permissions, usage_1h, usage_24h, usage_7d, usage_30d
Viewsapp_installation, permissions
Organizationsabilities
Support addressesbrands
View Execution / PreviewingThe following are automatically side-loaded if applicable: group, organization, users
SearchRecords related to type of records searched (mainly tickets, users, orgs). See Searches

The following Help Center API resources support side-loaded records:

Help Center API resourceSide-loaded records
Categoriestranslations
Sectionscategories, translations
Articlesusers, sections, categories, translations
Article commentsusers, articles, translations
Postsusers, topics
Post commentsusers, posts
Subscriptionsusers, articles, sections
Votesusers, articles, translations