Filtering #

Filtering by property is available on all the endpoints that list records.

All examples ignore authorization and use shortened URLs for brevity.

Reserved query string parameters #

Any query string parameter that begins with a dollar sign ($) has special meaning or handling and may or may not have an effect on filtering. Reserved parameters are documented where they are applicable.

Reserved parameters used by the filtering engine:

Basic filtering #

The simplest form of filtering uses plain query string parameters and direct comparisons for filtering. Reserved parameters are ignored. All applied filters must be true for a record to be returned. The backend uses a logical AND to join all filters. If the same property is specified multiple times, all values are merged into an array and the filter will allow any records that match all the values.

It is considered an error to have an empty right hand side for a filter parameter. The special null operator must be used to search for empty values.

Examples #

Get all work orders where priority is 2:

GET /maintenance/work_orders?priority=2

Get all work orders created belonging to a department:

GET /maintenance/work_orders?department_id=123

Get all work orders belonging to a department, and created today:

GET /maintenance/work_orders?department_id=123&created=2021-01-01

Searching by multiple values for the same property:

GET /maintenance/work_orders?department_id=123&department_id=456&department_id=789

The above would return all works orders that belong to departments 123, 456, and 789.

Get all work orders belonging to one of many departments and a priority:

GET /maintenance/work_orders?department_id=123&department_id=456&priority=3

Advanced filtering #

The API also supports advanced filtering by specifying an operator on the left hand side and prefixed with a colon (:). Advanced filtering does not allow for any grouping (parentheses, brackets) or logical operators (AND, OR, NOT). Advanced filtering is initiated if a colon is detected anywhere on the left hand side. Everything before the colon is assumed to be a property name. The colon is then stripped and the remaining text is used as the operator.

Examples #

Explicit direct comparison:

GET /maintenance/work_orders/54/notes?note:eq=some:value

Get all work orders created after a certain date:

GET /maintenance/work_orders?created:gt=2020-01-01

Get all work orders with a priority and that were created after a certain date:

GET /maintenance/work_orders?priority=3&created:gt=2020-01-01

Get all work orders from a set of departments and no priority:

GET /maintenance/work_orders?department_id=123&department_id=456&priority:null=

Note that simple and advanced filtering can be intermixed. The mode is determined on a parameter by parameter basis.

Get all work orders created in March of 2020:

GET /maintenance/work_orders?created:gte=2020-03-01&created:lte=2020-03-31

Available operators #

Pagination is always used for any endpoint that returns a list of records.