Wristband APIs that return a list of items often support filtering the returned results using a query expression. APIs that support the use of query expressions will have query query parameter. In the sections below, we'll go over how to write query expressions that can be passed to the query query parameter.

Query Syntax

Query expressions must follow this syntax:

<attribute> <comparison_operator> <value> [<logical_operator> ...]

Some example query expressions are listed below:

email eq "user@email.com"
givenName eq "Alice" or givenName eq "Bob"

In the next sections, we'll dive deeper into the different parts of a query expression.

Attributes

The attribute in a query expression specifies which entity attribute will be compared by the operator. The attributes you can use depend on the API being called. Refer to the Query Filter Attributes section in each API's description for a list of supported attributes.

Case Sensitivity

Attribute values are case-insensitive, so email and EMAIL are treated as equivalent.

Comparison Operators

The table below lists all supported comparison operators.

Operator	Description
eq	Equals
ne	Not Equals
sw	Starts With
lt	Less Than
le	Less Than or Equal
gt	Greater Than
ge	Greater Than or Equal
in	Multi-value comparison operator that resolves to true if an attribute’s value matches one of the values specified in the `in` value expression. The `in` value expression must be formatted as follows: `(<attribute_value>, <attribute_value>, ...)`.
nin	Multi-value comparison operator that resolves to true if an attribute’s value does not match one of the values specified in the `nin` value expression. The `nin` value expression must be formatted as follows: `(<attribute_value>, <attribute_value>, ... <attribute_value>")`.

Not all attributes support the same comparison operators. To see which operators are available for a given attribute, refer to the Query Filter Attributes section in the API's description.

Case Sensitivity

Comparison operator values are case-insensitive, so eq and EQ are treated as equivalent.

Attribute Values

The expected format of each attribute value depends on the type of the attribute. Currently, the following attribute types are supported:

String
Boolean

In the sections below, we'll provide a detailed overview of each attribute type.

String Attributes

String type attributes must have their values enclosed in double quotes (""). For example, if you wanted to filter users by their email, you would need to enclose the email value in double quotes, like the following:

email eq "user@email.com"

Escaping Special Characters

If you need to include special characters in the string value (such as double quotes), you'll have to escape them using the backslash (\) character. For example, if you wanted to include double quotes when querying by given name, you would need to escape the double quotes, like the following:

givenName eq "A \"Quoted\" String".

Case Sensitivity

The case sensitivity of the string value depends on the attribute being queried. To check the case sensitivity of an attribute, refer to the Query Filter Attributes section in the API's description.

Boolean Attributes

Boolean attributes must have a value of either true or false. Other truthy and falsy variations are not supported.

Null Values

If you want to query for attributes that don't have a value assigned, you can use null as the value. For example, if you wanted to filter for users that don't have a given name defined, you could use the following query:

givenName eq null.

Logical Operators

Logical operators can be used to combine predicate expressions in the query. Below is a table listing all the supported logical operators.

Logical Operator	Description
and	Logical "AND" operation.
or	Logical "OR" operation.

Case Sensitivity

Logical operator values are case-insensitive, so or and OR are treated as equivalent.

Order of Precedence

When multiple logical operators are used in a query expression and operators will evaluate first, followed by or operators. For example, if we had the following query expression:

email eq "mike@email.com" and givenName eq "mike" or lastName eq "smith"

First the email eq "mike@email" and givenName eq "mike"expression would be evaluated. Then the result of that expression would be combined with the lastName eq "smith"predicate using a logical or operator.

Grouping Operators

Parentheses can be used in queries to change the order of precedence when evaluating the expression. For example, if we had the following query expression:

email eq "mike@email.com" and (givenName eq "mike" or lastName eq "smith")

First the givenName eq "mike" or lastName eq "smith"expression would be evaluated. Then the result of that expression would be combined with the email eq "mike@email.com"predicate using a logical and operator.

Example Queries

Query for Users by Email and Status

email eq "user@email.com" and status eq "ACTIVE"

Query for Users by Email and Email Verified Status

email eq "user@email.com" and emailVerified eq true

Query for Users by Email or Username and Family Name

email eq "user@email.com" or username eq "bsmith" and familyName eq "Smith"

Query for Users by Email Using `in` Operator

email in ("user1@email.com", "user2@email.com", "user3@email.com")

Query for Users Whose Given Name is Null

givenName eq null

Query Entities Created After a Certain Datetime

metadata.creationTime gt "2021-06-13T19:00:00.000Z"

Query Syntax

Attributes

Case Sensitivity

Comparison Operators

Case Sensitivity

Attribute Values

String Attributes

Escaping Special Characters

Case Sensitivity

Boolean Attributes

Null Values

Logical Operators

Case Sensitivity

Order of Precedence

Grouping Operators

Example Queries

Query for Users by Email and Status

Query for Users by Email and Email Verified Status

Query for Users by Email or Username and Family Name

Query for Users by Email Using in Operator

Query for Users Whose Given Name is Null

Query Entities Created After a Certain Datetime

Query for Users by Email Using `in` Operator