Payload structure for a response with included resources

Some endpoints support the ability to query for a given type of resource and for related resource types. For example, the default behavior of the GET /activities endpoint is to return only activity resources. However, you can use the include query parameter to include any notes related to the returned activities in the response payload. These types of resources are referred to as included resources. The technique of adding included resources to a GET is sometimes referred to as response inclusion or read inclusion.

The syntax for adding included resources is:

<endpointPath>?include=<resourceName>
Java

where:

  • <endpointPath> is the default path, such as /common/v1/activities
  • <resourceName> is the name of the related resource, such as notes

For example GET /activities?include=notes returns all activities assigned to the current user, and all notes associated with those activities.

You can include multiple resource types in a single query. To do this, identify the resources in a comma-delimited list. For example, GET /policies?include=contacts,locations returns all policies assigned to the current user, and all contacts and locations associated with those policies.

When you execute a call with include, the response payload contains information about the primary resources and the included resources. However, most of the information about the included resources do not appear inline with the primary resources. Rather:

  • Every primary resource has a related section. This section lists the IDs (and types) of included resources related to that resource. However, each related section does not include any other details about those resources.
  • Details about the included resources appear at the end of the payload in a section called included.

The IDs of included objects appear in both the related section and the included section. You can use these IDs to match a primary resource with details about its included resources. However, the IDs of included objects are not globally unique.

Contrasting included resources and inlined resources

A response payload can contain two types of resources that have a relationship to the root resources: inlined resource and included resources. The following table contrasts the two types of resources.

Resource type How many related resources for each primary resource? Where do their fields appear? When do they appear?
Inlined resource Typically one. (For example, every activity has only one related assignedUser.) Entirely in the attributes section of the root resource If the query does not use the fields query parameter, then each inlined resource appears only if it is one of the default attributes.

If the query does use the fields query parameter, then each inlined resource does or does not appear based on whether it is specified in that query parameter.
Included resource One to many. (For example, every activity can have several related notes.) IDs appear in the related section of the root resource. The remaining attributes appear in the included section at the bottom of the payload.

When the query parameter includes the ?include=resourceName query parameter
Resource type How many related resources for each primary resource? Where do their fields appear? When do they appear?
Inlined resource Typically one. (For example, every activity has only one related assignedUser.) Entirely in the attributes section of the root resource If the query does not use the fields query parameter, then each inlined resource appears only if it is one of the default attributes.

If the query does use the fields query parameter, then each inlined resource does or does not appear based on whether it is specified in that query parameter.
Included resource One to many. (For example, every activity can have several related notes.) IDs appear in the related section of the root resource. The remaining attributes appear in the included section at the bottom of the payload.

When the query parameter includes the ?include=resourceName query parameter