Filtering

Collection endpoints support query parameters for filtering and sorting results.

• Some filters are single-value parameters: one parameter carries one value.
• Some filters are repeatable parameters: the same parameter name is sent with [] and can be provided multiple times.
• Repeated values for repeatable filters are OR-combined.

Single-value filters

Use these filters once per field.

If the same single-value filter is passed multiple times, the last value is generally the one that is applied. This is not a supported use case, however, and no guarantees are made about that behavior.

DateTime filter

Use gt, gte, lt, and lte for range filtering on date and time fields.

Accepted values include:

• Full ISO 8601 / RFC 3339 timestamps, such as 2026-01-01T00:00:00+00:00 or 2026-01-01T00:00:00Z
• Date-only values, such as 2026-02-01
• Relative date and time expressions, such as -30 minutes, yesterday, or first day of this month

Prefer a timestamp with an explicit timezone offset or Z to avoid ambiguity. A value without a timezone uses the server default timezone, Europe/Berlin.

Examples:

• createdAt[gt]=2026-01-01T00:00:00+00:00
• createdAt[gte]=-30 minutes
• createdAt[lte]=2026-01-31T23:59:59+00:00
• activatedAt[gte]=2026-01-01T00:00:00Z
• labIntakeAt[lt]=2026-02-01

Exists filter

Use this filter for resources where a property is present or absent. It is especially useful for nullable properties.

Examples:

• exists[activatedAt]=true
• exists[labIntakeAt]=false
• exists[unit]=true

Free-text query filter

Use this whitespace-tokenized search across a predefined group of fields behind one parameter.

The input is one string, such as Jane Doe. It is split into tokens such as Jane and Doe. Each token must match at least one configured field, so the token groups are AND-combined.

freeTextQuery[...] is a single-string, multi-field search parameter. Unlike repeatable filters, it is not sent with [].

It is more restrictive than query[...][] because all individual words must be present somewhere across the configured fields.

Example:

• freeTextQuery[name]=Jane Doe

Sort filter

Use this filter to control result ordering.

Examples:

• sort[createdAt]=asc
• sort[createdAt]=desc

Repeatable filters

These filters accept repeated values. Multiple values for the same filter are OR-combined.

Exact filter

Use this filter for exact matching on scalar values.

Examples:

• patient.dateOfBirth[]=1994-01-15
• patient.gender[]=F&patient.gender[]=D
• diagnosticOrder[]=00112233-4455-6677-8899-aabbccddeeff

Search filter

Use this filter for case-insensitive partial matching on one string field.

Examples:

• search[patient.firstName][]=Jane
• search[patient.lastName][]=Doe&search[patient.lastName][]=Miller
• search[patient.email][]=example.com

search[...][] targets one specific field per parameter. For example:

• search[patient.firstName][]=Jane&search[patient.lastName][]=Doe

This is the most explicit option because each field is filtered independently.

Query filter

Use this filter for case-insensitive partial matching across a predefined group of fields behind one parameter.

Multiple values for the same query[...][] parameter are OR-combined. Each value is checked against any field configured for that query profile.

query[...][] targets a predefined group of fields behind one parameter. For example:

• query[name][]=Jane&query[name][]=Doe
• query[onSiteBooking][]=ZKLAB

Unlike freeTextQuery[...], values are not tokenized automatically. query[name][]=Jane Doe searches for the full string Jane Doe as one value.

JSON filters

JSON filters target scalar values inside JSON object fields. Dot-separated paths such as metadata.reference address nested object keys.

json_exact and json_search are repeatable filters rendered as deepObject query parameters in OpenAPI, so their examples remain faithful to the request shape.

JSON exact filter

Use this filter for exact matching on scalar values inside JSON object fields using dot-separated paths.

OpenAPI example shape:

• json_exact[metadata.id]=["externalId","anotherId"]

JSON exists filter

Use this single-value filter to check whether a dot-separated path exists and its value is not JSON null.

Examples:

• json_exists[metadata.yourReference1]=true
• json_exists[metadata.partnerReference]=false

JSON search filter

Use this filter for case-insensitive partial matching on scalar values inside JSON object fields using dot-separated paths.

OpenAPI example shape:

• json_search[metadata.id]=["externalId","anotherId"]