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:

• Basic query syntax
• Searching in cURL
• Searching in Python 3
• Searching in Perl

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 .

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not support or guarantee the code. Zendesk also can't provide support for third-party technologies such as cURL, Python, and Perl.

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 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 properties such as created , updated , and solved 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 .

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 .

from urllib.parse import urlencode

import requests

credentials = 'your_zendesk_email', 'your_zendesk_password'
session = requests.Session()
session.auth = credentials

params = {
    'query': 'type:ticket status:open',
    'sort_by': 'created_at',
    'sort_order': 'asc'
}

url = 'https://your_subdomain.zendesk.com/api/v2/search.json?' + urlencode(params)
response = session.get(url)
if response.status_code != 200:
    print('Status:', response.status_code, 'Problem with the request. Exiting.')
    exit()

# Print the subject of each ticket in the results
data = response.json()
for result in data['results']:
    print(result['subject'])

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:

• LWP
• LWP::Protocol::https
• JSON

See these instructions.

use strict;
use warnings;
use LWP::UserAgent;
use JSON;
use MIME::Base64;
use URI::Escape;

my $credentials = encode_base64('your_email_address:your_password');

my %params = (
    query => 'type:ticket status:open',
    sort_by => 'created_at',
    sort_order => 'asc'
);

my $url = URI->new('https://your_subdomain.zendesk.com/api/v2/search.json');
$url->query_form(%params);

my $ua = LWP::UserAgent->new(ssl_opts =>{ verify_hostname => 0 });
my $response = $ua->get($url, 'Authorization' => "Basic $credentials");
die 'Status: ' . $response->code . '  ' . $response->message
    unless ($response->is_success);

# Print the subject of each ticket in the results
my $data = decode_json($response->content);
my @results = @{ $data->{'results'} };
foreach my $result ( @results ) {
    print $result->{"subject"} . "\n";
}