API Filter Syntax

This is the technical reference for the v2 Business Object filter syntax used in API requests. For a general overview of available operators, see Business Objects Filters.

The filter expression syntax is inspired by the SCIM (RFC 7644) and OData $filter languages.

Basic Syntax

{property} {operator} {value}

Multiple conditions are combined with AND (case-insensitive). OR logic is not supported.

{property1} {operator1} {value1} AND {property2} {operator2} {value2}

Property Paths

Business Object properties are referenced by their UUID:

properties.{propertyId}

Example:

properties.4eadbbe2-6d13-43d1-b90c-129e8860fbdb EQ active

The following built-in fields can also be filtered directly:

Field	Description
id or _id	The object's unique identifier
status	The object's built-in status field

Operators

All 16 operators are listed in the Business Objects Filters reference. Operators are case-insensitive.

= is accepted as an alias for EQ:

properties.{uuid}=active

Valueless operators (EMPTY, NEMPTY, ISME, NISME) take no value — only the property and operator are needed:

properties.{uuid} EMPTY
properties.{uuid} ISME

EQ matching behavior

EQ behaves differently depending on the property type:

• Text and string properties: case-insensitive match (e.g. EQ john matches John, JOHN, john)
• Numeric, boolean, and other non-text properties: exact type-aware match

Value Types

Values are automatically detected from their string representation — no quoting is needed:

Type	Format	Example
Integer	Whole number	42
Double	Decimal number	3.14
Boolean	true or false (case-insensitive)	true, True, TRUE
Time	HH:mm	09:30
Date	YYYY-MM-DD	2023-01-20
DateTime (with timezone)	ISO 8601 with Z or offset	2023-01-20T09:20:00.000Z
DateTime (without timezone)	ISO 8601 without timezone	2023-01-20T09:20:00.000
MongoDB ObjectId	24-character hex string	630f793d5e87014d50ffa457
String	Everything else	active, John Doe

Value Formats by Operator

IN / NIN — comma-separated values

properties.{uuid} IN value1,value2,value3
properties.{uuid} NIN value1,value2,value3

A JSON array is also accepted:

properties.{uuid} IN [value1,value2,value3]

RANGE — two comma-separated values (no brackets)

properties.{uuid} RANGE startValue,endValue

Both values must be the same type. Mixing formats (e.g. a timezone-aware DateTime with a timezone-naive one) is not supported and will result in an error.

Examples:

properties.{uuid} RANGE 10,100
properties.{uuid} RANGE 2023-01-01,2023-12-31
properties.{uuid} RANGE 09:00,17:00
properties.{uuid} RANGE 2023-01-20T09:00:00.000Z,2023-01-20T17:00:00.000Z

User-type properties — JSON object references

For User-type properties, IN and NIN values must be JSON objects with id (integer) and type (USER or GROUP):

properties.{uuid} IN {"id":123,"type":"USER"}
properties.{uuid} IN {"id":456,"type":"GROUP"}

Multiple references are comma-separated:

properties.{uuid} IN {"id":123,"type":"USER"},{"id":456,"type":"GROUP"}

Selection, Status, and Stages properties — label or ID

Values can be provided as either the option label (e.g., Active) or the option ID. Labels are automatically converted to the internal ID, so both produce the same result.

Examples

Simple equality

properties.{uuid} EQ John
properties.{uuid} EQ 2023-01-20

Numeric and date comparison

properties.{uuid} GT 18
properties.{uuid} RANGE 2023-01-01,2023-12-31

String search

properties.{uuid} CO important
properties.{uuid} SW Jo

Collection match

properties.{uuid} IN active,pending,review
properties.{uuid} NIN archived,deleted

Empty / non-empty checks

properties.{uuid} EMPTY
properties.{uuid} NEMPTY

Current user

properties.{uuid} ISME

Multiple conditions (AND only)

properties.{uuid1} EQ active AND properties.{uuid2} GT 18 AND properties.{uuid3} NEMPTY

Limitations

• OR logic is not supported. All conditions are combined with AND.
• ISME / NISME require the request to be authenticated.
• GT, GTE, LT, LTE, RANGE only work with numeric, date, and time value types.
• SW only works with string values.
• RANGE requires both values to be the same type — mixing formats (e.g. timezone-aware and timezone-naive DateTimes) will result in an error.
• IN / NIN with a boolean false value will also match null (fields with no value). This is by design to handle unset boolean fields.