When requesting items such as folders, packages, or tasks you can filter or restrict the set of results returned to those matching the criteria you specify.

There are two reasons to filter on the server (rather than iterating over the records client-side):

• you can reduce the size of the response by including only matching records
• logic is identical to that used by the web application

To filter, provide a parameter named ‘filter’ whose value is an array of one or more valid filter strings. The query string should look like:

?filter[]=filter_string_1&filter[]=filter_string_2&...

By default, the filter conjunction is assumed to be 'AND', such that only those items matching all supplied filters will be returned. If you specify filter_conjunction=OR, then items matching any of the supplied filters will be returned.

Each filter string has three parts:

• attribute
• operator
• value

Examples of filter strings:

owner_id = 23
is_done is false
is_on_hold is false
name starts_with BUG REPORT

You only need a space between the parts if they would otherwise “run together”, and any extra spaces are ignored. If the value has significant leading or trailing whitespace, throw single or double-quotes around it.

The best practice is to always put a space between the parts, and always put quotes around the value part. But if you forget, we try to be forgiving.

For example, these are all valid and mean the same thing:

owner_id=23
owner_id =23
owner_id= 23
owner_id = 23

But the following are invalid:

namestarts_withBugReport
name starts_withBugReport
namestarts_with BugReport

and require whitespace:

name starts_with BugReport

Single or double-quote the value if it contains significant leading or trailing whitespace. For example:

name contains "Bug Report  "

will only match items whose name contains “Bug Report ” (where it is followed by two spaces). Without the quotes, the trailing spaces would be ignored (and you’d match any “Bug Report”, with or without spaces after it).

Available Filters

ID Filters

Use the operators ”=” and “!=” to match those items that do or do not have a specific ID set. The value should be an ID number; in the case of ‘owner_id’ and ‘created_by’, you can also use the magical value ‘me’.

• owner_id
• created_by
• client_id
• project_id
• package_id

Boolean Filters

The operator for boolean filters is always “is”, and the value is either “true” or “false”.

• is_done
• is_on_hold
• has_comments
• has_alert
• needs_update

String Filters

Operators are ”=” (exact match, case sensitive), “starts_with” (case-insensitive prefix match), and “contains” (case-insensitive substring match).

• name
• reference

Date Filters

The are several operators available for date attributes; not all are available for all attributes.

For the before and after operators, you can specify one of several magical values: yesterday, today, tomorrow, and infinity.

These are the operators:

and these are the attributes along with their applicable operators: