Filter

Filter inputs are used to retrieve Records with one or more filter criterions from an App. They can be provided when retrieving Records with one of the following endpoints:

Retrieve filtered Records for an App: Get filtered Records

For every supported endpoint, multiple filters can be provided which get concatenated with the boolean AND operator.

The following example matches all records that have a field value for field with ID 1 containing the text "John" and a field value for field with ID 2 equal to 123:

JSON

➡️      Single Text Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "single_text",
      "match_type": "contains",
      "values": [
        {
          "value": "John"
        }
      ],
      "type": "text"
    },
    {
      "field_id": "2",
      "field_type": "status",
      "match_type": "equal",
      "values": [
        {
          "value": 123
        }
      ],
      "type": "status"
    }
  ]
}

Single Text

This is an example on how to filter records by a single_text field:

JSON

➡️      Single Text Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "single_text",
      "match_type": "contains",
      "values": [
        {
          "value": "John"
        }
      ],
      "type": "text"
    }
  ]
}

The following match_type values are supported for single_text fields:

Match type	Description
`equal`	Matches all records whose field value is equal to the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` is equal to `"john doe"`
`not_equal`	Matches all records whose field value is not equal to the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` is equal to `"john doe"`, `"johnny doe"` is not equal to `"john doe"`
`contains`	Matches all records whose field value contains the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` contains `"doe"`
`not_contains`	Matches all records whose field value does not contain the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` does not contain `"Johnny"`
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Multi Text

This is an example on how to filter records by a multi_text field:

JSON

➡️      Multi Text Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "multi_text",
      "match_type": "contains",
      "values": [
        {
          "value": "John"
        }
      ],
      "type": "text"
    }
  ]
}

The following match_type values are supported for multi_text fields:

Match type	Description
`equal`	Matches all records whose unformatted field value is equal to the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` is equal to `"john doe"`
`not_equal`	Matches all records whose unformatted field value is not equal to the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` is equal to `"john doe"`, `"johnny doe"` is not equal to `"john doe"`
`contains`	Matches all records whose unformatted field value contains the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` contains `"doe"`
`not_contains`	Matches all records whose unformatted field value does not contain the provided match value. Comparison is case insensitive and spaces are ignored. `" John Doe "` does not contain `"Johnny"`
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Single Category

This is an example on how to filter records by a single_category field:

JSON

➡️      Single Category Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "single_category",
      "match_type": "any",
      "values": [
        {
          "value": 1
        },
        {
          "value": "Not Started"
        }
      ],
      "type": "category"
    }
  ]
}

Either the id of the respective category option or the label of the option can be provided as match value. The following match_type values are supported for single_category fields:

Match type	Description
`equal`	Matches all records whose field value references the category option specified by the match value. Comparison is case insensitive and spaces are ignored.
`not_equal`	Matches all records whose field value does not reference the category option specified by the match value. Comparison is case insensitive and spaces are ignored.
`any`	Matches all records whose field value references any of the category options specified by the match value. Comparison is case insensitive and spaces are ignored.
`none`	Matches all records whose field value does not reference any of the category options specified by the match value. Comparison is case insensitive and spaces are ignored.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Multi Category

This is an example on how to filter records by a multi_category field:

JSON

➡️      Multi Category Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "multi_category",
      "match_type": "any",
      "values": [
        {
          "value": 1
        },
        {
          "value": "Not Started"
        }
      ],
      "type": "category"
    }
  ]
}

Either the id of the respective category option or the label of the option can be provided as match value. The following match_type values are supported for multi_category fields:

Match type	Description
`equal`	Matches all records whose field value exactly references all category options specified by the match value and no more. Comparison is case insensitive, spaces are ignored and the order of options has no influence
`not_equal`	Matches all records whose field value exactly references all category options specified by the match value and no more. Comparison is case insensitive, spaces are ignored and the order of options has no influence
`any`	Matches all records whose field value references any category option of those provided by the match value. Comparison is case insensitive and spaces are ignored
`none`	Matches all records whose field value references no category option of those provided by the match value. Comparison is case insensitive and spaces are ignored
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Single Relation

This is an example on how to filter records by a single_relation field:

JSON

➡️      Single Relation Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "single_relation",
      "match_type": "any",
      "values": [
        {
          "value": 1
        }
      ],
      "type": "app"
    }
  ]
}

Provide the related record IDs to filter by.

The following match_type values are supported for single_relation fields:

Match type	Description
`equal`	Matches all records whose field value references the records specified by the match value.
`not_equal`	Matches all records whose field value does not reference the records specified by the match value.
`any`	Matches all records whose field value references any of the records specified by the match value.
`none`	Matches all records whose field value does not reference any of the records specified by the match value.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Multi Relation

This is an example on how to filter records by a multi_relation field:

JSON

➡️      Multi Relation Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "multi_relation",
      "match_type": "any",
      "values": [
        {
          "value": 1
        }
      ],
      "type": "app"
    }
  ]
}

Provide the related record IDs to filter by.

The following match_type values are supported for multi_relation fields:

Match type	Description
`equal`	Matches all records whose field value exactly references records specified by the match value and no more.
`not_equal`	Matches all records whose field value exactly references records specified by the match value and no more.
`any`	Matches all records whose field value references any category option of those provided by the match value.
`none`	Matches all records whose field value references no category option of those provided by the match value.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Single User

This is an example on how to filter records by a single_user field:

JSON

➡️      Single User Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "single_user",
      "match_type": "any",
      "values": [
        {
          "value": 1
        }
      ],
      "type": "contact"
    }
  ]
}

Provide the user IDs to filter by.

The following match_type values are supported for single_user fields:

Match type	Description
`equal`	Matches all records whose field value references the users specified by the match value.
`not_equal`	Matches all records whose field value does not reference the users specified by the match value.
`any`	Matches all records whose field value references any of the users specified by the match value.
`none`	Matches all records whose field value does not reference any of the users specified by the match value.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Multi User

This is an example on how to filter records by a multi_user field:

JSON

➡️      Multi User Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "multi_user",
      "match_type": "any",
      "values": [
        {
          "value": 1
        }
      ],
      "type": "contact"
    }
  ]
}

Provide the user IDs to filter by.

The following match_type values are supported for multi_user fields:

Match type	Description
`equal`	Matches all records whose field value exactly references the users specified by the match value and no more.
`not_equal`	Matches all records whose field value exactly references the users specified by the match value and no more.
`any`	Matches all records whose field value references any of the users provided by the match value.
`none`	Matches all records whose field value references none of the users provided by the match value.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Status

This is an example on how to filter records by a status field:

JSON

➡️      Status Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "status",
      "match_type": "any",
      "values": [
        {
          "value": 1
        },
        {
          "value": "Not Started"
        }
      ],
      "type": "status"
    }
  ]
}

Either the id of the respective status option or the label of the option can be provided as match value. The following match_type values are supported for status fields:

Match type	Description
`equal`	Matches all records whose field value references the status option specified by the match value. Comparison is case insensitive and spaces are ignored.
`not_equal`	Matches all records whose field value does not reference the status specified by the match value. Comparison is case insensitive and spaces are ignored.
`any`	Matches all records whose field value references any of the category options specified by the match value. Comparison is case insensitive and spaces are ignored.
`none`	Matches all records whose field value does not reference any of the category options specified by the match value. Comparison is case insensitive and spaces are ignored.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty
`completed`	Matches all records whose referenced option is set to `completed`
`incomplete`	Matches all records whose referenced option is set to `incomplete`

Number

This is an example on how to filter records by a number field:

JSON

➡️      Number Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "number",
      "match_type": "smaller",
      "values": [
        {
          "value": 12.34
        }
      ],
      "type": "number"
    }
  ]
}

Match type	Description
`equal`	Matches all records whose field value is equal to the provided match value
`smaller`	Matches all records whose field value is smaller than the provided match value
`smaller_or_equal`	Matches all records whose field value is smaller or equal to the provided match value
`larger`	Matches all records whose field value is larger than the provided match value
`larger_or_equal`	Matches all records whose field value is larger or equal to the provided match value
`not_equal`	Matches all records whose field value does not reference the status specified by the match value. Comparison is case insensitive and spaces are ignored.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Single Date

This is an example on how to filter records by a single_date field:

JSON

➡️      Single Date Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "single_date",
      "match_type": "is_before",
      "relative_date_type": "exact_date",
      "values": [
        {
          "value": "2020-01-01"
        }
      ],
      "type": "date"
    },
    {
      "field_id": "1",
      "field_type": "single_date",
      "match_type": "is_after",
      "relative_date_type": "num_weeks_before",
      "values": [
        {
          "value": "2020-01-01",
          "offset_amount": 1
        }
      ],
      "type": "date"
    }
  ]
}

In addition to the match type, a relative date type needs to be provided when filtering for a Single Date Field: num_days_after, num_days_before, num_weeks_after, num_months_before, num_months_after, exact_date.

The combination of the provided match value, the offset amount and the relative date type will be used to calculate the date to match against. E.g. if the match value is 2020-01-01, the offset amount is 1 and the relative date type is num_days_before, the date to match against will be 2019-12-31.

Match type	Description
`equal`	Matches all records whose field value is equal to the the date of the provided match value + offset_amount + relative_date_type
`not_equal`	Matches all records whose field value is not equal to the the date of the provided match value + offset_amount + relative_date_type
`before`	Matches all records whose field value is before the date of the provided match value + offset_amount + relative_date_type
`on_or_before`	Matches all records whose field value is before the date of the provided match value + offset_amount + relative_date_type
`after`	Matches all records whose field value is after the date of the provided match value + offset_amount + relative_date_type
`on_or_after`	Matches all records whose field value is after the date of the provided match value + offset_amount + relative_date_type
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Created At

This is an example on how to filter records by a created_at field:

JSON

➡️      Created At Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "created_at",
      "match_type": "is_before",
      "relative_date_type": "exact_date",
      "values": [
        {
          "value": "2020-01-01"
        }
      ],
      "type": "date"
    },
    {
      "field_id": "1",
      "field_type": "created_at",
      "match_type": "is_after",
      "relative_date_type": "num_weeks_before",
      "values": [
        {
          "value": "2020-01-01",
          "offset_amount": 1
        }
      ],
      "type": "date"
    }
  ]
}

In addition to the match type, a relative date type needs to be provided when filtering for a Created At Field: num_days_after, num_days_before, num_weeks_after, num_months_before, num_months_after, exact_date.

Match type	Description
`equal`	Matches all records whose creation date is equal to the the date of the provided match value + offset_amount + relative_date_type
`not_equal`	Matches all records whose creation date is not equal to the the date of the provided match value + offset_amount + relative_date_type
`before`	Matches all records whose creation date is before the date of the provided match value + offset_amount + relative_date_type
`on_or_before`	Matches all records whose creation date is before the date of the provided match value + offset_amount + relative_date_type
`after`	Matches all records whose creation date is after the date of the provided match value + offset_amount + relative_date_type
`on_or_after`	Matches all records whose creation date is after the date of the provided match value + offset_amount + relative_date_type

Last Modified At

This is an example on how to filter records by a last_modified_at field:

JSON

➡️      Last Modified At Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "last_modified_at",
      "match_type": "is_before",
      "relative_date_type": "exact_date",
      "values": [
        {
          "value": "2020-01-01"
        }
      ],
      "type": "date"
    },
    {
      "field_id": "1",
      "field_type": "last_modified_at",
      "match_type": "is_after",
      "relative_date_type": "num_weeks_before",
      "values": [
        {
          "value": "2020-01-01",
          "offset_amount": 1
        }
      ],
      "type": "date"
    }
  ]
}

In addition to the match type, a relative date type needs to be provided when filtering for a Last Modified At Field: num_days_after, num_days_before, num_weeks_after, num_months_before, num_months_after, exact_date.

Match type	Description
`equal`	Matches all records whose date of last modification is equal to the the date of the provided match value + offset_amount + relative_date_type
`not_equal`	Matches all records whose date of last modification is not equal to the the date of the provided match value + offset_amount + relative_date_type
`before`	Matches all records whose date of last modification is before the date of the provided match value + offset_amount + relative_date_type
`on_or_before`	Matches all records whose date of last modification is before the date of the provided match value + offset_amount + relative_date_type
`after`	Matches all records whose date of last modification is after the date of the provided match value + offset_amount + relative_date_type
`on_or_after`	Matches all records whose date of last modification is after the date of the provided match value + offset_amount + relative_date_type

Multi Email

This is an example on how to filter records by a multi_email field:

JSON

➡️      Multi Email Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "multi_email",
      "match_type": "fully_includes",
      "values": [
        {
          "value": "[email protected]"
        }
      ],
      "type": "email"
    }
  ]
}

Match type	Description
`fully_includes`	Matches all records whose field value includes at least one email entry containing the full number specified by the match value. Comparison is case insensitive and spaces are ignored.
`starts_with`	Matches all records whose field value includes at least one email entry that starts with the match value. Comparison is case insensitive and spaces are ignored.
`ends_with`	Matches all records whose field value includes at least one email entry that ends with the match value. Comparison is case insensitive and spaces are ignored.
`contains`	Matches all records whose field value includes at least one email entry that contains the match value. Comparison is case insensitive and spaces are ignored.
`not_contains`	Matches all records whose field value includes at least one email entry that does not contain the match value. Comparison is case insensitive and spaces are ignored.
`empty`	Matches all records whose field value is empty. I.e. does not contain any email entry
`not_empty`	Matches all records whose field value is not empty. I.e. contains at least one email entry

Multi Phone

This is an example on how to filter records by a multi_phone field:

JSON

➡️      Multi Phone Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "multi_phone",
      "match_type": "starts_with",
      "values": [
        {
          "value": "+49"
        }
      ],
      "type": "phone"
    }
  ]
}

Match type	Description
`fully_includes`	Matches all records whose field value includes at least one phone entry containing the full address specified by the match value. Comparison is case insensitive and spaces are ignored.
`starts_with`	Matches all records whose field value includes at least one phone entry that starts with the match value. Comparison is case insensitive and spaces are ignored.
`ends_with`	Matches all records whose field value includes at least one phone entry that ends with the match value. Comparison is case insensitive and spaces are ignored.
`contains`	Matches all records whose field value includes at least one phone entry that contains the match value. Comparison is case insensitive and spaces are ignored.
`not_contains`	Matches all records whose field value includes at least one phone entry that does not contain the match value. Comparison is case insensitive and spaces are ignored.
`empty`	Matches all records whose field value is empty. I.e. does not contain any phone entry
`not_empty`	Matches all records whose field value is not empty. I.e. contains at least one phone entry

Calculation

This is an example on how to filter records by a calculation field:

JSON

➡️      calculation Filter
{
  "filters": [
    {
      "field_id": "1",
      "field_type": "calculation",
      "match_type": "smaller",
      "values": [
        {
          "value": 12.34
        }
      ],
      "type": "calculation"
    }
  ]
}

Note that the calculation field is polymorphic, and may contain textual, numeric or date results (with or without time). Refer to the individual field types as the calculation field expects the same filtering format for these different types.

Match type	Description
`equal`	Matches all records whose field value is equal to the provided match value
`smaller`	Matches all records whose field value is smaller than the provided match value
`smaller_or_equal`	Matches all records whose field value is smaller or equal to the provided match value
`larger`	Matches all records whose field value is larger than the provided match value
`larger_or_equal`	Matches all records whose field value is larger or equal to the provided match value
`not_equal`	Matches all records whose field value does not reference the status specified by the match value. Comparison is case insensitive and spaces are ignored.
`empty`	Matches all records whose field value is empty
`not_empty`	Matches all records whose field value is not empty

Single Text​

Multi Text​

Single Category​

Multi Category​

Single Relation​

Multi Relation​

Single User​

Multi User​

Status​

Number​

Single Date​

Created At​

Last Modified At​

Multi Email​

Multi Phone​

Calculation​