Reference
Filtering

Filtering

This page documents the filter query parameter, supported operators, syntax rules, and value constraints for the Protime API.

Filter query parameter

Filters are passed via the filter query parameter on GET collection endpoints:

GET /connector/protimeapi/api/v1/<resource-collection>?filter=<filter-expression> HTTP/1.1
Host: <tenant>.myprotime.eu

Most collection endpoints require at least one filter condition. A request without a required filter, or with a malformed filter expression, returns 400 Bad Request.

Some collection endpoints do not support filters at all; their Filters section in the collection reference states this. These endpoints always return the complete collection and reject any request that includes the filter query parameter with 400 Bad Request.

Filter operators

Comparison operators

Operator Description Example
eq Equals kind eq 'Activity'
ge Greater than or equal date ge '2024-01-01'
le Less than or equal date le '2024-01-31'
in In list person in (1, 2, 3)

Named in-collections

The in operator supports an optional identifier that specifies a named collection:

Form Example
in circle(...) person in circle(2, 8)
in org-group(...) person in org-group(121, 122)

Named in-collections are available on the person filter. They select the people who are members of the given circles or org-groups at the moment of the request.

Logical operators

Operator Description Example
and Logical AND person in (1,2,3) and date ge '2024-01-01'
or Logical OR kind eq 'Activity' or kind eq 'Absence'

or is only supported on fields with the Multiple constraint category. Using or on Single or Range fields returns 400 Bad Request.

Parentheses may be used to group sub-expressions: (kind eq 'Activity' or kind eq 'Absence') and date ge '2024-01-01'.

Expression grammar

The filter expression follows this grammar:

expression       = term { "or" term }.
term             = condition { "and" condition }.
condition        = simple-condition | "(" expression ")".
simple-condition = identifier rel-op factor.
rel-op           = "eq" | "ge" | "le" | "in".
factor           = constant | list.
constant         = integer | string | bool.
list             = [identifier] "(" constant { "," constant } ")".

Value types

Filter fields accept values of specific types. The type determines what literal format the value must use in the filter expression.

Type Literal format Example
Integer Unquoted digits person in (1, 2, 3)
String Single-quoted kind eq 'Activity'
Date Single-quoted, yyyy-MM-dd date ge '2024-01-01'
GUID Single-quoted id eq 'b2347a7a-d60d-446f-b03b-7e52cc8c3281'
Boolean Unquoted true or false enabled eq true

Field constraint categories

Each filterable field enforces one of three constraint categories:

Category Allowed operators Description
Single eq, in (one value) Accepts exactly one value per field.
Multiple eq, in Accepts one or more values. Repeated conditions are combined.
Range eq, ge, le Accepts a start value (ge), end value (le), or both. eq sets both start and end to the same value.

URL encoding

Filter expressions in query strings must be URL-encoded. Spaces become %20, single quotes become %27.

Example (URL-encoded):

GET /connector/protimeapi/api/v1/clockings?filter=person%20in%20(1,2,3)%20and%20date%20ge%20'2024-01-01'%20and%20date%20le%20'2024-01-05' HTTP/1.1
Host: <tenant>.myprotime.eu

Maximum URL length

The API enforces a maximum URL length of 4096 characters. Requests that exceed this limit receive a 414 URI Too Long response.

See also

ResponsesDelta