Searching with the Zendesk API
The Zendesk REST API provides the following single, unified API for searching Zendesk Support resources such as tickets, users, organizations, and groups:
GET /api/v2/search.json?query={search_string}
This guide shows you how to use it. Topics covered:
For the reference doc, see Ticketing - Search API .
A different API is provided for searching Help Center content. It uses defined URL parameters for advanced searches instead of the query syntax discussed in this article. For more information, see Help Center API - Search .
Basic query syntax
The search API has a URL parameter named query :
.../api/v2/search.json?query={search_string}
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:
Search for a specific word
query=Greenbriar
Search for an exact string
query="Greenbriar Corporation"
Search for a ticket by id
query=3245227
Search by resource type
query=type:user "Jane Doe"
Search by ticket status
query=type:ticket status:open
Search by date
query=type:organization created<2015-05-01
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,
"", are used for search phrases. Only records containing an exact match of the phrase are returned. -
The
typeproperty returns records of the specified resource type. Possible values includeticket,user,organization, orgroup. Learn more about types . -
The
statusproperty returns tickets set to the specified status. Possible values includenew,open,pending,hold,solved, orclosed. Learn more about ticket properties . You can also search by user, organization, and group properties. -
Date properties such as
created,updated, andsolvedreturn 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 .
Searching in cURL
Using the search API with plain cURL can be a pain because the search string needs to be url-encoded. Example:
curl "https://{subdomain}.zendesk.com/api/v2/search.json?query=type%3Aticket+status%3Aopen" \-v -u {email_address}:{password}
You can use clean query syntax by using 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}
The -G flag specifies that the url-encoded data is for a GET request rather than a POST request. The data is appended to the URL with a '?' separator.
For more information on cURL, see Installing and using cURL .
Searching in Python 3
Let's say you want to search for all open tickets:
.../search.json?query=type:ticket status:open
The URL parameter has to be url-encoded for the request. In Python 3, you can use the urlencode() method to encode the URL parameters.
Start by importing the method from the urllib.parse module:
from urllib.parse import urlencode
Next, add the query parameter as a name/value pair in a Python dictionary:
params = { 'query': 'type:ticket status:open' }
The urlencode() method takes a dictionary of parameters, not a string. If you want to sort the results too, add the extra parameters to the dictionary:
params = {'query': 'type:ticket status:open','sort_by': 'created_at','sort_order': 'asc' # from oldest to newest}
Finally, url-encode the parameters and make the request:
url = 'https://{subdomain}.zendesk.com/api/v2/search.json?' + urlencode(params)response = requests.get(url)
Below is an example script. For clarity, it doesn't paginate through the results even though it should. To learn how, see Paginating through lists . To run the script, replace the placeholders with your information. You'll also need to download and install the Requests library if you don't already have it. See these instructions .
To learn more, see:
- Paginating through lists
- Making requests to the Zendesk API
- Python learning resources
- Think Python by Allen B. Downey*
Searching in Perl
Assume you want to search for all open tickets:
.../search.json?query=type:ticket status:open
The URL parameter has to be url-encoded for the request. In Perl, you can use the URI::Escape module to url-encode the URL parameters.
Start by including the module in your script:
use URI::Escape;
Next, add the query parameter as a name/value pair in a Perl hash:
my %params = (query => 'type:ticket status:open');
The URI method used to url-encode URL parameters takes a hash, not a string. If you want to sort the results too, add the extra parameters to the hash:
my %params = (query => 'type:ticket status:open',sort_by => 'created_at',sort_order => 'asc' # from oldest to newest);
Define the search URL as a new URI object:
my $url = URI->new('https://{subdomain}.zendesk.com/api/v2/search.json');
Use the object's query_form() method to url-encode the parameters and add them to the URL as a query string:
$url->query_form(%params);
Finally, create a user agent and make the request:
my $ua = LWP::UserAgent->new(ssl_opts =>{ verify_hostname => 0 });my $response = $ua->get($url, 'Authorization' => "Basic $credentials");
Below is an example script. For clarity, it doesn't paginate through the results even though it should. To learn how, see Paginating through lists . To run the script, replace the placeholders with your information. You'll also need to download and install the following modules if you don't already have them:
See these instructions .