Filtering allows you to limit the results of a search to only the items that match specific criteria.

This is done using the POST /api/<entity>/search search endpoints, which are available for nearly all entities in the API. These endpoints accept structured parameters in the request body, making filtering consistent, readable, and easy to extend.

Basic Structure

A typical filter request body looks like this (e.g. for the endpoint POST /api/units/search):

{
  "entranceId": 3245
}

⇒ This would return all units where the entranceId is 3245.

These available parameters vary from entity to entity, so be sure to check out the respective search endpoint. But there are generally available parameters across all search endpoints:

`searchTerm`

searchTerm is a filter parameter that is generally available for all search endpoints and is actually used by most of the endpoints. It is then used, if supported, for a case-insensitive free-text lookup of core fields such as name, number, or label.

{
  "searchTerm": "Street"
}

⇒ This returns only the items where the keyword "Street" matches a searchable property

📘
Entity-specific
Whether searchTerm is supported or which fields it searches depends on the specific entity.

`ids`

All search endpoints support filtering by ids:

{
  "ids": [101, 102, 103]
}

⇒ This returns only the items with those exact IDs. It’s helpful when resolving known references or working with a prefiltered dataset.

Combining Filters

Multiple filters can be used together. They are (nearly) always combined using AND logic — meaning that all conditions must match for a record to be included.

{
  "typeId": 1,
  "entranceId": 3245
}

⇒ This returns only items where both typeId and entranceId match exactly.

Exact Matching Only

In general, filtering uses exact matching — there’s no built-in support (if not stated differently by the particular parameter) for:

partial matches or wildcards
numeric ranges (e.g. greater than, less than)
logical OR across different fields

If you need more flexible logic, it must be handled outside the request.

Filtering with Sorting and Pagination

Filtering works hand-in-hand with sorting and pagination. You can add:

an orderBy array to define sorting (see Sorting)
pageNumber and pageSize values for paginated results (see Pagination)

Full Example

POST /api/units/search

{
  "pageNumber": 0,
  "pageSize": 2,
  "typeId": 1,
  "entranceId": 3245,
  "ids": [101, 102, 103],
  "searchTerm": "Street",
  "orderBy": ["number asc"]
}

This request returns the first two Units where:

the typeId is 1
the entranceId is 3245
the id is one of [101, 102, 103]
and the keyword "Street" matches a searchable property (unit.number or unit.position in this case)

Results are sorted by number in ascending order.