Introduction

If an endpoint for listing some entity has a parameter filter_str, then the endpoint can be filtered on one or several of the fields it contains.

Most "List..." endpoints (List Customers, List Customerinvoices etc.) have this parameter, which means you have many more options than just getting a value by id in this case.

This is one of the most useful features in the API, so read this section carefully.

Usage

The filter_str-parameter should be a valid JSON string representing an object with keys found in the endpoint schema, with or without a constraint suffix appended to the key.

Each key-value pair in the provided JSON object is one filter constraint, and the endpoint will return objects that match all the constraints.

There are six possible kinds of filtering constraints:

"fieldname" I.e. a key with the same name as a key in the response schema. This is an equality constraint. Only records that have this exact value for the field are matched.
"fieldname__le" and "fieldname__ge" are "lesser than or equal" and "greater than or equal" constraints. Numerical values are compared with natural ordering and string values are compared with lexicographical ordering.
"fieldname__lt" and "fieldname__gt" are "lesser than" and "greater than" constraints. Numerical values are compared with natural ordering and string values are compared with lexicographical ordering.
"fieldname__ne" is a "not equal" constraint. Only records that do not have this exact value for the field are matched.
"fieldname__in" is a set membership constraint. It should be given as a list of values of the same type that the field has. Records match if they match any of the values in the list exactly.
"fieldname__contains" is a substring constraint and is only available for fields of string type. Records match if the value of the record contains the given string as a substring. The matching is case-insensitive.

Constraints can be combined to create more complex filters. As an example for the endpoint /project/, the following filter_str uses most of the constraints above:

{
  "customerid":32,
  "workplacecity": null,
  "startdate__ge":"2021-01-01",
  "startdate__le":"2021-12-31",
  "note__in": ["Very long", null],
  "name__contains": "highway"
}

This filter could be used to get all projects that:

are for a specified customer with customerid=32
does not specify a workplace city
started during 2021
has a note with the value "Very long" OR lacks a value
has a name that contains "highway" as a substring

If the given filter is invalid JSON or contains keys that are not valid filters, an HTTP 422 - Unprocessable Entity response will be returned.