Overview of query parameters

When you execute a system API call using only the endpoint (as in GET /activities), the response payload has a default set of resources and a default structure.

You may want to refine the response payload beyond the default behavior by:

  • Specifying a custom set of properties.
  • Filtering out resources that do not meet a given criteria
  • Sorting the resources
  • Limiting the number of elements returned in each payload
  • Retrieving a count of the total number of resources in the database that meet the query's criteria

You can refine the response payload using query parameters. A query parameter is an expression added to the HTTP request that modifies the default response payload.

A system API call can include any number of query parameters. The list of query parameters starts with a question mark (?). If there are multiple query parameters, each is separated by an ampersand (&). For example:

  • GET /activities?fields=*all
  • GET /activities?filter=escalated:eq:false
  • GET /activities?fields=*all&filter=escalated:eq:false

Included resources

You can use the include query parameter to include resources related to the primary resources of the response. You can also use query parameters to specify a custom set of properties for included resources, filter out included resources that do not meet a given criteria, sort the included resources, and so on. For more information, see Using query parameters on included resources.

Viewing query parameter documentation in Swagger UI

For every endpoint, Swagger UI provides descriptions of the query parameters supported by that endpoint. This information is hidden by default. To show the descriptions, click the endpoint's operation button (such as the GET button for GET /activities). The query parameter descriptions appear under the endpoint.

Parameter definitions

The Parameters section describes each query parameter.

Supported parameters

The Responses section include a Model tab. This tab provides information about the fields that support particular query parameters. For example, you can sort results on some fields, but not all of them. The fields that support sorting appear in the model with the text "sortable": true.

Query parameter error messages

If you attempt to use a query parameter on a field that does not support that parameter, the system API returns a 400 Bad Request error and an error message. For example, if you execute: GET /activities?sort=escalationDate, the system API provides the following error message:

"message": "The sort column 'escalationDate' is not a valid option. The valid 
      sort options are [assignedUser, dueDate, escalated, priority, status, subject], 
      optionally prefixed with '-' to indicate a descending sort."