Value Filters

Value Filters restrict GET results by comparing public fields with request values. Filters use AND semantics when a request contains multiple conditions.

Filtering a related field adds a relation constraint. Public fields on the requested resource and its publicly accessible relations can be addressed with dot notation.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?filter - Query parameter containing the field filters.

• [{field}] - Public field to which the filter applies.

• [{filter}] - Filter key documented below. Defaults to value when omitted.

• {value} - Request value compared with the affected field.

GET /api/{route}?filter[{field}][{filter}]={value}

Value Filters can address fields on related records and nested relations.

?filter[user.role.department.title]=TestDepartment

Filtering a related field restricts the parent records. Use include separately to return the related records.

Use camelCase for relation names and snake_case for field keys.

Value

The value filter performs a case-insensitive partial comparison equivalent to LIKE. It returns records whose affected field contains {value}.

GET /api/{route}?filter[{field}][value]={value}

Is Value

The is filter performs an exact = comparison and returns records whose affected field equals {value}.

GET /api/{route}?filter[{field}][is]={value}

Is Not Value

The not filter performs a != comparison and returns records whose affected field does not equal {value}.

GET /api/{route}?filter[{field}][not]={value}

Greater Than

The gt filter performs a > comparison and returns records whose affected field is greater than {value}.

GET /api/{route}?filter[{field}][gt]={value}

Greater Than or Equal

The gte filter performs a >= comparison and returns records whose affected field is greater than or equal to {value}.

GET /api/{route}?filter[{field}][gte]={value}

Less Than

The lt filter performs a < comparison and returns records whose affected field is less than {value}.

GET /api/{route}?filter[{field}][lt]={value}

Less Than or Equal

The lte filter performs a <= comparison and returns records whose affected field is less than or equal to {value}.

GET /api/{route}?filter[{field}][lte]={value}

Null Checks

The is_null filter accepts 0 or 1.

Pass 1 to return records whose affected field is null.

GET /api/{route}?filter[{field}][is_null]={1}

Pass 0 to return records whose affected field is not null.

GET /api/{route}?filter[{field}][is_null]={0}

In

The in filter accepts comma-separated values or an array and returns records whose affected field equals any supplied value.

GET /api/{route}?filter[{field}][in]={value}

An empty item includes records whose field is null. For example, filter[folder_id][in]=1, matches folder 1 or no folder; filter[folder_id][in]= matches only null. A literal 0 is a regular value. An empty array matches no records.

Not In

The nin filter accepts comma-separated values or an array and excludes records whose affected field equals a supplied value.

GET /api/{route}?filter[{field}][nin]={value}

An empty item adds a not-null condition. For example, filter[folder_id][nin]= matches records with a folder. When non-empty values are supplied, the database comparison also excludes null fields. An empty array adds no restriction.

Period

The period filter accepts two comma-separated dates and returns records whose affected field lies within that period.

GET /api/{route}?filter[{field}][period]={value}