Search

The search API is a unified search API that returns tickets, users, and organizations. You can define filters to narrow your search results according to resource type, dates, and object properties, such as ticket requester or tag.

To search articles in Help Center, see Search in the Help Center API documentation.

To use the API with Python or Perl, see Zendesk REST API tutorial: Searching.

Note: It can take up to a few minutes for new tickets, users, and other resources to be indexed for search. If new resources don't appear in your search results, wait a few minutes and try again.

Query basics

You specify search queries in a URL parameter named query:

.../search.json?query={search_string}

Syntax examples

The query syntax for {search_string} is detailed in the Zendesk Support search reference, but this section gives a quick overview. The syntax gives you a lot of flexibility. Examples:

Query Returns
query=3245227 The ticket with the id 3245227
query=Greenbriar Any record with the word Greenbriar
query=type:user "Jane Doe" User records with the exact string "Jane Doe"
query=type:ticket status:open Open tickets
query=type:organization created<2015-05-01 Organizations created before May 1, 2015
query=status<solved requester:user@domain.com type:ticket Unsolved tickets requested by user@domain.com
query=type:user tags:premium_support Users tagged with premium_support
query=created>2012-07-17 type:ticket organization:"MD Photo" Tickets created in the MD Photo org after July 17, 2012

How it works:

  • The : character is the equality operator. Other operators include < and >, the minus sign -, and the wildcard character *. Learn more about the operators.

  • Double quotes, "", specify a search phrase. Stemming is used for the results. For example, the search results for "top" will include data that match the string "top" as a single word, a single word in a longer phrase ("top tier"), or the prefix of a longer word ("topology"). It won't include data where the string "top" appears in the middle or end of a word ("stopwatch", "desktop").

  • The type property returns records of the specified resource type. Possible values include ticket, user, organization, or group. Learn more about types.

  • The status property returns tickets set to the specified status. Possible values include new, open, pending, hold, solved, or closed. Learn more about ticket properties. You can also search by user, organization, and group properties.

  • Date-time properties such as created, updated, and solved can return records for a specific date, on or before a certain date, and on or after a certain date. The date format is YYYY-MM-DD. Learn more about dates.

URL-encoding the search string

Because a search string is sent in a HTTP request, the string must be url-encoded. Example:

?query=type%3Aticket+status%3Aopen

Most HTTP libraries provide tools for url-encoding strings. In cURL, you can use the --data-urlencode option with the -G flag:

curl "https://{subdomain}.zendesk.com/api/v2/search.json" \
-G --data-urlencode "query=type:ticket status:open" \
-v -u {email_address}:{password}

In Python 3, you can use the urlencode() method in the urllib.parse module.

For examples, see Zendesk REST API tutorial: Searching.

JSON Format

Queries are represented as JSON objects which have the following keys.

Name Type Comment
count integer The total number of results matching this query
next_page string URL to the next page of results
prev_page string URL to the previous page of results
results array May consist of Tickets, Users, Groups, Organizations, and Topics. A result_type value is added to each result object and can have the following values: ticket, user, group, organization, topic.
Example
{
  "results": [
    {
      "name":        "Hello DJs",
      "created_at":  "2009-05-13T00:07:08Z",
      "updated_at":  "2011-07-22T00:11:12Z",
      "id":          211,
      "result_type": "group"
      "url":         "https://foo.zendesk.com/api/v2/groups/211.json"
    },
    {
      "name":        "Hello MCs",
      "created_at":  "2009-08-26T00:07:08Z",
      "updated_at":  "2010-05-13T00:07:08Z",
      "id":          122,
      "result_type": "group"
      "url":         "https://foo.zendesk.com/api/v2/groups/122.json"
    },
    ...
  ],
  "facets":    null,
  "next_page": "https://foo.zendesk.com/api/v2/search.json?query=\"type:Group hello\"&sort_by=created_at&sort_order=desc&page=2",
  "prev_page": null,
  "count":     1234
}

Search

GET /api/v2/search.json?query={search_string}

Allowed for:
  • Agents and admins
Available parameters
Name Type Required Comments
query string yes The search query
sort_by string no One of updated_at, created_at, priority, status, or ticket_type. Defaults to sorting by relevance
sort_order string no One of asc or desc. Defaults to desc

Use the ampersand character (&) to append the sort_by or sort_order parameters to the URL. Example:

https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed&sort_by=status&sort_order=desc

For Python or Perl examples, see Zendesk REST API tutorial: Searching.

Query

See Query basics above. For details on the query syntax, see the Zendesk Support search reference.

Using curl
curl "https://{subdomain}.zendesk.com/api/v2/search.json" \
  -G --data-urlencode "query=type:ticket status:open" \
  -v -u {email_address}:{password}

Errors JSON Format

Errors are represented as JSON objects which have the following keys:

Name Type Comment
error string The type of error. e.g.: 'unavailable', 'invalid'
description string
Example
{
  "error": "unavailable",
  "description": "Sorry, we could not complete your search query. Please try again in a moment."
}