Filtering Requests (LP Classic)

When requesting Treeitems, Tasks, Events, Partial Day Events, Milestones, Folders, Projects, or Packages, 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 a 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).

If your search string contains double quotes, enclose it in single quotes and if it contains single quotes, use double quotes around it. You can also escape your quotes with a backslash, for example:

name contains "Don't"
name contains 'Don\'t'

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 or a comma separated list of ID numbers. In the case of owner_id, created_by, and updated_by, you can also use the magical value me. The values everyone and unassigned are usable for owner_id.

• id - Can use comma-separated multiple Item IDs like this: filter[]=id=1111,2222,3333
• activity_id - Also has the operator “none” for nothing assigned.
• client_id
• created_by
• owner_id
• package_id - Matches tasks that are packaged in a package with this id.
• parent_id
• project_id
• updated_by

Boolean Filters

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

• all_dependencies_satisfied
• has_alert
• has_an_activity
• has_broken_dependencies
• has_comments
• has_dependencies
• has_dependents
• has_documents
• has_reference
• is_done
• is_in_a_project
• is_on_hold
• is_packaged
• shared
• needs_update

String Filters

Available Operators

Attributes

• name
• reference

Number Filters

Operators are =, !=, >, <, >=, <=.

Item Type Filters

If you make a request that returns multiple types of items, such as getting treeitems, tasks, or events, you can filter to show only one type.

Operators are = (exact match on the type), and is (also includes subclass types, ex: includes partial day events when filtering on event).

• item_type - Options are: "Package", "Project", "Folder", "Task", "Event", "Milestone"

Date Filters

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

Operators

Attributes

📘

The promise_by date attribute corresponds to the Deadline date field in the application UI.

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems?filter[]=promise_by after 2018-04-07

🚧

The date filters are an exception from ISO 8601 date format; they use yyyy-mm-dd format for the dates and default to the midnight of the API user's timezone.

Pick List Custom Fields

The attribute for Pick List Custom fields is custom_field:id or custom_field:name

Available Operators:

• is_set
• is_not_set
• =
• !=

Example:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/treeitems?filter[]=custom_field:foo=bar

Pick List Custom fields can also be filtered with URL parameters custom_field[Field Name]=Value, for example:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks?custom_field[foo]=bar

Text Custom Fields

The attribute for Text Custom fields is custom_field:id or custom_field:name

Available Operators:

• is_set
• is_not_set
• =
• contains
• starts_with
• does_not_start_with

Example:

% curl https://app.liquidplanner.com/api/v1/workspaces/:id/tasks?filter[]=custom_field:foo starts_with bar

Date Custom Fields

The attribute for Text Custom fields is custom_field:id or custom_field:name

Example:

% curl https://app.liquidplanner.com/api/workspaces/:id/tasks?filter[]=custom_field:‘contract date’ within 7

Tag Filters

The operator for tag filtering is include. You may provide a single tag, as in:

filter[]=tags include Alpha

or multiple tags, as in:

filter[]=tags include Bravo, Charlie, Delta 

If you provide multiple tags, the set of items returned will consist of all items tagged with any of the provided tags. In the previous filter, all items returned will be tagged with at least one of "Bravo", "Charlie", or "Delta".

To filter items such that every item is tagged with all specified tags, you must specify the tag filter multiple times- as in:

filter[]=tags include Echo&filter[]=tags include Foxtrot&filter[]=tags include Golf

With this filter, all items returned will be tagged with all three tags.