# Value Filters

## Introduction

ValueFilters offer the possibility to alter the query of a GET-request,\
so that the response contains only the data you are looking for.

As the name indicates, ValueFilters limit the response of a GET-request by validating whether the value of `{field}` matches the expression out of `{filter}` and `{value}`.

Filters are applied as AND queries. If relation-fields are filtered, there will be a **has** constraint applied.

Every public field of the entity the endpoint belongs to, as well as every field\
of related entities, can be filtered.

### Definition

* `{route}` - The endpoint you want to retrieve data of
* `?filter` - To identify the incoming URL parameter
* `[{field}]` - The field the filter will be applied to
* `[{filter}]` - One of the filters listed below. Defaults to [value](#value) when not provided.
* `=[{value}]` - The value(s) that get compared with the value in `[{field}]`

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][{filter}]={value}`

{% hint style="info" %}
You can apply filters on fields of a related record and even their relations, too.

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

Note that every relation which is accessed with the query will be resolved and returned by the API.
{% endhint %}

{% hint style="warning" %}
Relations are always in `camelCase`, while field keys are in `snake_case`.
{% endhint %}

## Value

This filter operates the same way as a `like`.

Returns all entries for which the value of `{field}` is contained in `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][value]={value}`

## Is Value

Filter that depicts the functionality of the comparison-operator `=`

Returns the entries for which the value of `{field}` equals `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][is]={value}`

## Is Not Value

Filter that depicts the functionality of the comparison-operator `!=`

Returns all entries for which the value of `{field}` doesn't equal `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][not]={value}`

## Greater Than

Filter that depicts the functionality of the comparison-operator `>`

Returns all entries for which the value of `{field}` is greater than `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][gt]={value}`

## Greater Than Equal

Filter that depicts the functionality of the comparison-operator `>=`

Returns all entries for which the value of `{field}` is greater than `{value}` or for which the value of `{field}` equals `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][gte]={value}`

## Lower Than

Filter that depicts the functionality of the comparison-operator `<`.

Returns all entries for which the value of `{field}` is lower than `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][lt]={value}`

## Lower Than Equal

Filter that depicts the functionality of the comparison-operator `<=`.

Returns all entries for which the value of `{field}` is lower than `{value}` or for which the value of `{field}` equals `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][lte]={value}`

## Is Null / Is Not Null

This filter expects an integer, which can be `0` or `1`.

Returns all entries for which the value of `{field}` is `NULL`, when `{value}` is set to `1`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][is_null]={1}`

Returns all entries for which the value of `{field}` is `NOT NULL`, when `{value}` is set to `0`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][is_null]={0}`

## In

This filter expects a string with one or more values, which must be comma-separated.

Returns all entries for which the value of `{field}` equals one of the values in `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][in]={value}`

## Not In

This filter expects a string with multiple values, which must be comma-separated.

Returns the entries for which the value of `{field}` doesn't equal one of the values in `{value}`.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][nin]={value}`

## Period

This filter expects a string with two date values, which must be comma-separated.

Returns the entries, that lie between those two dates.

<mark style="color:green;">`GET`</mark> `/api/{route}?filter[{field}][period]={value}`