Filtering

Filtering Query Language

Some resources support retrieval with filtering by way of a query parameter in the request URI. This section outlines terminology, field types, and syntax for requesting resources that support filtering.

Terminology

A filter query clause consists of a field followed by an operator followed by a value. A keyword combines clauses:

Terminology	Example
clause	`name:"DailyPay"`
expression	`name~"ADP" AND name~"LLC"`
field	`name`
operator	`:`
value	`DailyPay`
keyword	`AND`

Field Types

Type	Description
string	String values must be enclosed in double quotes. Double quotes within a string must be escaped with the `\` character."`

Filter Syntax

The following table lists operator and keyword syntax that you can use to construct and combine clauses:

Syntax	Usage	Description	Example
`:`	`field:value`	Exact Match operator (case insensitive)	`name:"DailyPay"` returns records where name is exactly "DailyPay"
`~`	`field~value`	Partial Match operator (case insensitive)	`name~"Daily"` returns records whose name includes "Daily", such as "PaidDaily" and "DailyPay"
`AND`, `and`	field1:value1 AND field2:value2	this filter returns records that match both clauses	`name~"Daily" AND name~"LLC"` returns records whose name partially matches both "Daily" and "LLC"
`OR`, `or`	field1:value1 or field2:value2	this filter returns records that match either clauses	`name~"Daily" OR name~"LLC"` returns records whose name partially matches either "Daily" or "LLC"
`\`	`"\" \""`	Escape character for quotes within quotes	`description:"An \"earned wage access\" company`

Note

Exact match may accept multiple values separated by commas without whitespace.

Example: status:"IN_TRANSIT","PROCESSING","DEPOSITED" returns records whose status is one of "IN_TRANSIT", "PROCESSING", or "DEPOSITED"

Parenthesis

Parentheses are used to group expressions together and control the order of evaluation. By using parentheses, you can create complex filter conditions that combine multiple criteria in a clear and unambiguous way. Here's how you can use parenthesis:

Controlling Evaluation Order

Parentheses control the order in which expressions are evaluated. Without parentheses, the filter conditions are evaluated from left to right. Using parentheses allows you to specify the evaluation order explicitly.

Example

GET /paychecks?filter=person_id:"aa860051-c411-4709-9685-c1b716df611b" AND (status:"DEPOSITED" OR status:"IN_TRANSIT")

In this example, the API will retrieve paychecks whose status is "DEPOSITED" OR "IN_TRANSIT" belonging to the person of specified id. The parentheses ensure that the OR condition is evaluated first, and then the AND condition is applied to the result.

Nested Parenthesis

You can also use nested parentheses to create more complex filter conditions. By nesting parentheses, you can create intricate combinations of filtering criteria.

Example

GET /organizations?filter=((status:"pending" or status:"active") and (name~"INC" or name~"LLC"))

In this example, the api will retrieve all organizations who are active or pending and whose name contains "INC" or "LLC"