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](#syntax)
* [Searching in cURL](#curl)
* [Searching in Python 3](#python)
* [Searching in Perl](#perl)

For the reference doc, see [Core API - Search](https://developer.zendesk.com/rest_api/docs/core/search).

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](https://developer.zendesk.com/rest_api/docs/help_center/search#content).

<div class="note note"><span class="notetitle">Disclaimer: </span>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. Please post any issue in the comments section or search for a solution online.</div>

<!--
title: Zendesk REST API tutorial: Searching with the Zendesk API
url: https://support.zendesk.com/hc/en-us/articles/205364368
source: _dev_guide/search.md
-->

<h3 id="syntax">Basic query syntax</h3>

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](https://support.zendesk.com/hc/en-us/articles/203663226), 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](https://support.zendesk.com/hc/en-us/articles/203663226#topic_ngr_frb_vc).

* 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](https://support.zendesk.com/hc/en-us/articles/203663226#topic_qtr_avw_ld).

* 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](https://support.zendesk.com/hc/en-us/articles/203663226#topic_crj_yev_uc). 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](https://support.zendesk.com/hc/en-us/articles/203663226#topic_gbg_dvw_ld).


<h3 id="curl">Searching in cURL</h3>

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](https://support.zendesk.com/hc/en-us/articles/203691436).

<h3 id="python">Searching in Python 3</h3>

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 = request.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](https://support.zendesk.com/hc/en-us/articles/204232743). To run the script, replace the placeholders with your information. You'll also need to download and install the [Requests](http://docs.python-requests.org/en/latest/) library if you don't already have it. See [these instructions](http://docs.python-requests.org/en/latest/user/install/#install).

<script src="https://gist.github.com/chucknado/3d26957f348924bf9602.js"></script>

To learn more, see:

* [Paginating through lists](https://support.zendesk.com/hc/en-us/articles/204232743)
* [Zendesk REST API tutorial - Python edition](https://support.zendesk.com/hc/en-us/articles/203691316)
* [Dive into Python 3](http://www.diveintopython3.net/) by Mark Pilgrim
* [Think Python](http://www.greenteapress.com/thinkpython/html/index.html) by Allen B. Downey* 

<h3 id="perl">Searching in Perl</h3>

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](https://support.zendesk.com/hc/en-us/articles/204232743). 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](http://search.cpan.org/~mschilli/libwww-perl-6.08/lib/LWP.pm)
* [LWP::Protocol::https](http://search.cpan.org/~mschilli/LWP-Protocol-https-6.06/lib/LWP/Protocol/https.pm)
* [JSON](http://search.cpan.org/%7Emakamaka/JSON-2.90/lib/JSON.pm)

See [these instructions](http://www.cpan.org/modules/INSTALL.html).

<script src="https://gist.github.com/chucknado/f62e18f4047fef26d0f7.js"></script>

To learn more, see:

* [Paginating through lists](https://support.zendesk.com/hc/en-us/articles/204232743)
* [Zendesk REST API tutorial - Perl edition](https://support.zendesk.com/hc/en-us/articles/203691306)
* [Learn Perl in about 2 hours 30 minutes](http://qntm.org/files/perl/perl.html) by Sam Hughes
* [Learning Perl, 6th Edition](http://www.amazon.com/Learning-Perl-Randal-L-Schwartz/dp/1449303587), by Randal L. Schwartz