Filtering API v3 results

With API v3 you have an option to use filters to get specific results.

After recent changes, GET /tickets API requests are processed by Elastic search instead of searching directly through the database. Due to these changes, some requests to retrieve lists of tickets might work differently since version 5.43, for example using a filter {"subject":"order"} searches all tickets containing the word "order", e.g. tickets with the subject "Order #123", "Order #456", or even "Order-inquiry".

From version 5.51.5.29 there is also an important change in allowed filters, for more information please see this article.

While retrieving a list of tickets, it is possible to use the search parameter to retrieve the same results as while searching in the agent panel, e.g. _filters={"search":"order"}.

Parameters owner_email, owner_name, last_activity_public, public_access_urlcode, and custom_fields cannot be used in filters.

Simple filters

Using a simple filter you can filtrate results by searching for a specific column with an exact value:

{"parameter":"value"}

This simple filter allows you to retrieve e.g. tickets with New status:

_filters:{"status":"N"}

You can also combine more conditions in a filter by separating them by a comma, e.g. searching in contacts for all men in a company with a specific ID:

_filters={"gender":"M","company_id":"123abc"}

Using the simple filter, you can search only for a specific value in a parameter, but cannot define operators or use e.g. date ranges. To define operators or search for results within date ranges, use an advanced filter.

Advanced filters

The format of a filter for advanced search requires three values instead of two as in simple filter:

[["parameter","operator","value"]]

As you can see an operator is used in it. With an advanced filter, you can search e.g. for tickets created only this week or all tickets that are not deleted:

_filters=[["date_created","DP","TW"]]
_filters=[["status","NE","X"]]

You can also combine more conditions into one filter by separating them by a comma, e.g. searching for all postponed tickets created the last month:

_filters=[["status","E","W"],["date_created","DP","LM"]]

Operators used in advanced search

In all advanced filters you can use the following operators:

Operators E, NE, IN, NI, and PM cannot be used to filtrate tags.