Filtering

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 must be a valid JSON string representing an object.
Each key in this object must correspond to a field defined in the endpoint schema and may include an optional constraint suffix.

Each key-value pair defines a single filter condition, and the endpoint returns only objects that satisfy all specified conditions.

Value Formatting

For each field type, values in the filter_str JSON must follow these formatting rules:

Text fields: Enclose values in quotation marks.
Example:
```
{ "name": "Bridge maintenance" }
```
Numerical fields: Use raw JSON numbers (no quotation marks).
Examples:
```
{ "customerid": 32 }
{ "budgethours__ge": 40.5 }
```
Boolean fields: Use lowercase true or false.
Example:
```
{ "approved": false }
```
Date fields: Represent dates as strings using the yyyy-mm-dd format. Represent datetime fields using the yyyy-mm-ddThh:mm:ss convention.
Example:
```
{ "startdate": "2026-06-30" }
{ "created__ge": "2026-06-30T13:01:01" }
```
Null values: Use the JSON null keyword to find records missing a value.
Example:
```
{ "workplacecity": null }
```

Additional details are available in the Formats and encoding section.

Supported Filter Constraints

Equality - fieldname
Matches records with exactly this value.
Not equal - fieldname__ne
Matches records where the field value differs from the specified value.
Range comparisons:

Numerical values are compared with natural ordering and string values are compared with lexicographical ordering.
- fieldname__lt - Matches records with values < the given value.
- fieldname__le - Matches records with values ≤ the given value.
- fieldname__gt - Matches records with values > the given value.
- fieldname__ge - Matches records with values ≥ the given value.
Set membership — fieldname__in
Value must be one of the items in a provided list. The list must use the same data type as the field.
Substring match — fieldname__contains
Matches text fields where the value includes the given substring (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.

This can happen when:

filter_str is not valid JSON
the JSON object contains a field that is not valid for the endpoint
the JSON object contains an unsupported filter suffix
the value does not match the field type
__contains is used on a field that is not a string
__in is not given as an array