Zendesk Support API Searches

The Zendesk Support API allows users to perform searches across various entities such as tickets, users, groups, and organizations. This guide covers how to effectively use the search functionality, including filtering, sorting, and pagination options.

What can you do with Searches in the Zendesk Support API?

The most common operations people perform on searches using the Zendesk Support API.

Action	HTTP Method	Endpoint
List Search Results	`GET`	`/api/v2/search`
Show Results Count	`GET`	`/api/v2/search/count`
Export Search Results	`GET`	`/api/v2/search/export`

The Search entity in the Zendesk Support API allows users to query across multiple resources such as tickets, users, groups, and organizations.

Searches are performed using query strings that specify the criteria for the search.

Searches are not created as persistent entities but are executed as queries against the Zendesk database.

Searches can be refined using query parameters such as query, sort_by, and sort_order. For example, to search for closed tickets, use query=type:ticket status:closed.

Properties of a Search

This section outlines the key properties of the Search entity, focusing on those most relevant for developers when performing searches. Show all properties Only show essential properties

Field Name	Type	Short Description
id	integer	The ID of the resource.
name	string	The name of the resource.
created_at	string	When the resource was created.
updated_at	string	When the resource was last updated.
description	string	The description of the resource.
result_type	string	The type of the resource.
url	string	The URL of the resource.
default	boolean	Flag to indicate whether this is the default resource.
deleted	boolean	Flag to indicate whether or not the resource has been deleted.
active	boolean	Filter by active views if true or inactive views if false.
access	string	Filter views by access. May be 'personal', 'shared', or 'account'.
group_id	integer	Filter views by group.
external_id	string	The `external_id` parameter does not support the search syntax. It only accepts ids.
photo_url	string	URL of Avatar.
agents	array	List of agents in the search result.
groups	array	List of groups in the search result.
approval_requests	array	List of approval requests in the search result.
automations	array	List of automations in the search result.
custom_object_records	array	List of custom object records in the search result.
triggers	array	List of triggers in the search result.
users	array	List of users in the search result.

Show all properties

Filtering and Query Parameters

The Zendesk Support API supports a variety of filtering and sorting options to refine search results.

Parameter	Type	Description	Example
`query`	string	The search query string.	`type:ticket status:closed`
`sort_by`	string	Sort results by a specific field such as <code>updated_at</code> or <code>created_at</code>.	`updated_at`
`sort_order`	string	Specify the order of sorting, either <code>asc</code> or <code>desc</code>.	`desc`
`filter[type]`	string	Specify the object type for export queries. Can be <code>ticket</code>, <code>organization</code>, <code>user</code>, or <code>group</code>.	`ticket`
`page[size]`	integer	The number of results shown in a page.	`100`

What to watch out for

Here are some common pitfalls and important considerations when using the Zendesk Support Search API.

Query Syntax

Ensure your query strings are correctly formatted according to the Zendesk Support search syntax. Improperly formatted queries will result in errors.

Pagination Limits

The Search Requests endpoint returns up to 1,000 results per query, with a maximum of 100 results per page. Exceeding these limits will result in a 422 Insufficient Resource Error.

Rate Limiting

The Export Search Results endpoint is rate-limited to 100 requests per minute per account. Ensure your application handles rate limits gracefully.

Frequently Asked Questions

This section addresses frequently asked questions about using the Zendesk Support API for searches, helping developers troubleshoot common issues and optimize their queries.

How do I sort search results in Zendesk Support?

You can sort search results using the sort_by and sort_order query parameters. For example, to sort by creation date in descending order, use sort_by=created_at&sort_order=desc.

What happens if I exceed the pagination limits in a search request?

If you request a page past the limit (e.g., page=11 at 100 results per page), the API will return a 422 Insufficient Resource Error. Consider using the Export Search Results endpoint for larger datasets.

Can I search for multiple object types in a single query?

No, the Export Search Results endpoint only returns results of a single object type, specified by the filter[type] parameter. Ensure your query specifies the correct object type.

How do I handle rate limits when using the Search API?

Implement retry logic with exponential backoff in your application to handle rate limits gracefully. Monitor your API usage to stay within the allowed limits.

Why is my search query returning no results?

Ensure your query string is correctly formatted and that the criteria match existing records. Check for typos and ensure the fields you're querying are indexed.