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".

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.

Boolean operators
Operator Description Example use
L Like [["tags","L","3bg4"]]
NL Not like [["tags","NL","3bg4"]]
E Equals [["status","E","N"]]
NE Not equals [["status","NE","X"]]
CY Contains any of [["tags","CY","3bg4,9aue"]]
IN Is in [["departmentid","IN","8ld2hdk5,klt0srua"]]
NI Not in [["departmentid","NI","default,8ld2hdk5"]]
IE Is empty [["company_id","IE",""]]
INE Is not empty [["company_id","INE",""]]
Numerical value operators
Operator Description Example use
= Number equals [["id","=","209"]]
> Number greater than [["id",">","200"]]
< Number lower than [["id","<","51"]]
>= Number equals or is greater [["id",">=","78"]]
<= Number equals or is lower [["id","<=","3"]]
Date & time operators
Operator Description Example use
D= Date equals [["date_created","D=","2011-11-11"]]
D> Date greater than [["date_changed","D>","2023-01-01 13:00:00"]]
D< Date lower than [["date_created","D>","2022-12-31"]]
D>= Date equals or is greater [["last_activity","D>=","2023-12-24 7:00:00"]]
D<= Date equals or is lower [["last_activity","D<=","2022-11-30"]]
T= Time equals  
T> Time greater than  
T< Time lower than  
T>= Time equals or is greater  
T<= Time equals or is lower  
DP Date range [["date_created","DP","TW"]]
Date & time operators' values
Value Description Example use
T Today [["date_created","DP","Y"]]
Y Yesterday [["date_created","DP","T"]]
L7D Last 7 days [["date_created","DP","L7D"]]
L30D Last 30 days [["date_created","DP","L30D"]]
L90D Last 90 days [["date_created","DP","L90D"]]
TW This week [["date_created","DP","TW"]]
LW Last week [["date_created","DP","LW"]]
L2W Last 2 weeks [["date_created","DP","L2W"]]
LWW Last week workdays [["date_created","DP","LWW"]]
TM This month [["date_created","DP","TM"]]
LM Last month [["date_created","DP","LM"]]
TY This year [["date_created","DP","TY"]]
LY Last year [["date_created","DP","LY"]]