Filtering

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 common parameters shared by many or all search endpoints:

searchTerm

searchTerm is a filter parameter supported by most search endpoints. It performs 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

searchTerm is only listed in the request body of a search endpoint if that endpoint supports it. Its description there names the fields that are searched. Endpoints that don't list searchTerm ignore it.

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.

Timestamp filters

The following parameters are available on all search endpoints for entities that track creation and modification timestamps:

changedSince is the broadest filter — it matches any entity touched (created or modified) since the given point in time, making it ideal for incremental sync or polling for updates:

{
  "changedSince": "2025-01-01T00:00:00Z"
}

⇒ Returns entities where created >= "2025-01-01T00:00:00Z" or lastModified >= "2025-01-01T00:00:00Z".

The narrower filters (createdFrom, createdUntil, lastModifiedFrom, lastModifiedUntil) can be combined for precise ranges:

{
  "createdFrom": "2025-01-01T00:00:00Z",
  "createdUntil": "2025-06-30T23:59:59Z"
}

⇒ Returns only entities created within the first half of 2025.

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.