Filtering

Many list-style Management API endpoints accept a filter query parameter to narrow down results — for example listing users, listing groups, listing Authorisations, and listing user directories, among others.

Syntax

The filter syntax is similar to SCIM/RFC7644 but with some small changes:

• Attribute names are case sensitive
• "Complex attribute filter grouping" is not supported
• Not all attributes are searchable, while some hidden attributes may be searchable. Please complain when you find these issues.

The filter is given with a filter parameter, such as:

filter=username eq "john"

Operators

Supported operators are as listed in RFC7644:

Operator	Description	Notes
eq	equal	The attribute and operator values must be identical for a match. This can be used also to search from an array, for example if the parameter's value is an array of strings ["value1", "value2"] and a filter like parameterName eq "value1" is used, then that object would be returned.
ne	not equal	The inverse of eq: a match requires the attribute and operator values to differ.
co	contains	The entire operator value must be a substring of the attribute value for a match.
sw	starts with	The attribute value must begin with the entire operator value for a match.
ew	end with	The attribute value must end with the entire operator value for a match.
pr	present (has value)	Matches if the attribute has any value at all. Used without a value, for example customFields.myKey pr.
gt	greater than	Match if the attribute value sorts after the operator value — usable with numbers and DateTime values, not just plain strings.
ge	greater than or equal to	Same comparison as gt, but also matches when the values are equal.
lt	less than	Match if the attribute value sorts before the operator value — usable with numbers and DateTime values, not just plain strings.
le	less than or equal to	Same comparison as lt, but also matches when the values are equal.

Attribute operator	Description	Behavior
and	Logical "and"	The filter is only a match if both expressions evaluate to true.
or	Logical "or"	The filter is a match if either expression evaluates to true.
not	"Not" function	The filter is a match if the expression evaluates to false.

Logical operator	Description	Behavior
( )	Precedence grouping	Groups a sub-expression so it's evaluated as a single unit before combining it with and/or/not, the same way parentheses work in most programming languages.
[ ]	Complex attribute filter grouping is NOT SUPPORTED	In standard SCIM, this restricts a filter to values within the same entry of a multi-valued complex attribute (for example emails[type eq "work" and value co "@example.com"]). This API doesn't support that syntax.

Combine operators to filter on more than one condition at once:

filter=(type eq "file_for_permit" or type eq "sales_permit") and not (revoked eq true)

Value types

Quote a value with double quotes to filter on a string; leave boolean and numeric values unquoted:

filter=locked eq true
filter=customFields.my_number gt 5

DateTime filtering

Filter expressions where the value is a string in double quotes and can be parsed as an ISO Instant string, are used as DateTime filters. For example:

Examples

filter=createdDate gt "2017-10-20T07:17:17.606Z"
filter=lastModifiedDate le "2019-05-31T23:59:59.999Z"

Finding filterable fields for an endpoint

Not every field on a resource is filterable, and the operators a field supports can vary — for example, a free-text field may support co (contains) while a boolean field only supports eq/ne/pr. Each endpoint that accepts a filter parameter documents its own filterable fields and their supported operators in that parameter's own description, in your instance's /apidoc page.

Some resources also expose a special, endpoint-specific filter field of their own. For example, listing groups supports searchText, a free-form search field that can be combined with the rest of the filter using a logical and:

filter=searchText eq "myvalue -excludevalue"