Skip to main content

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:

➡️    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:

➡️    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 typeDescription
equalMatches 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_equalMatches 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"
containsMatches all records whose field value contains the provided match value. Comparison is case insensitive and spaces are ignored. " John Doe " contains "doe"
not_containsMatches 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"
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Multi Text

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

➡️    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 typeDescription
equalMatches 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_equalMatches 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"
containsMatches all records whose unformatted field value contains the provided match value. Comparison is case insensitive and spaces are ignored. " John Doe " contains "doe"
not_containsMatches 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"
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Single Category

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

➡️    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 typeDescription
equalMatches all records whose field value references the category option specified by the match value. Comparison is case insensitive and spaces are ignored.
not_equalMatches all records whose field value does not reference the category option specified by the match value. Comparison is case insensitive and spaces are ignored.
anyMatches all records whose field value references any of the category options specified by the match value. Comparison is case insensitive and spaces are ignored.
noneMatches 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.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Multi Category

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

➡️    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 typeDescription
equalMatches 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_equalMatches 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
anyMatches all records whose field value references any category option of those provided by the match value. Comparison is case insensitive and spaces are ignored
noneMatches all records whose field value references no category option of those provided by the match value. Comparison is case insensitive and spaces are ignored
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Single Relation

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

➡️    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 typeDescription
equalMatches all records whose field value references the records specified by the match value.
not_equalMatches all records whose field value does not reference the records specified by the match value.
anyMatches all records whose field value references any of the records specified by the match value.
noneMatches all records whose field value does not reference any of the records specified by the match value.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Multi Relation

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

➡️    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 typeDescription
equalMatches all records whose field value exactly references records specified by the match value and no more.
not_equalMatches all records whose field value exactly references records specified by the match value and no more.
anyMatches all records whose field value references any category option of those provided by the match value.
noneMatches all records whose field value references no category option of those provided by the match value.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Single User

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

➡️    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 typeDescription
equalMatches all records whose field value references the users specified by the match value.
not_equalMatches all records whose field value does not reference the users specified by the match value.
anyMatches all records whose field value references any of the users specified by the match value.
noneMatches all records whose field value does not reference any of the users specified by the match value.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Multi User

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

➡️    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 typeDescription
equalMatches all records whose field value exactly references the users specified by the match value and no more.
not_equalMatches all records whose field value exactly references the users specified by the match value and no more.
anyMatches all records whose field value references any of the users provided by the match value.
noneMatches all records whose field value references none of the users provided by the match value.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Status

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

➡️    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 typeDescription
equalMatches all records whose field value references the status option specified by the match value. Comparison is case insensitive and spaces are ignored.
not_equalMatches all records whose field value does not reference the status specified by the match value. Comparison is case insensitive and spaces are ignored.
anyMatches all records whose field value references any of the category options specified by the match value. Comparison is case insensitive and spaces are ignored.
noneMatches 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.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty
completedMatches all records whose referenced option is set to completed
incompleteMatches all records whose referenced option is set to incomplete

Number

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

➡️    Number Filter
{
"filters": [
{
"field_id": "1",
"field_type": "number",
"match_type": "smaller",
"values": [
{
"value": 12.34
}
],
"type": "number"
}
]
}
Match typeDescription
equalMatches all records whose field value is equal to the provided match value
smallerMatches all records whose field value is smaller than the provided match value
smaller_or_equalMatches all records whose field value is smaller or equal to the provided match value
largerMatches all records whose field value is larger than the provided match value
larger_or_equalMatches all records whose field value is larger or equal to the provided match value
not_equalMatches all records whose field value does not reference the status specified by the match value. Comparison is case insensitive and spaces are ignored.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Single Date

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

➡️    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 typeDescription
equalMatches all records whose field value is equal to the the date of the provided match value + offset_amount + relative_date_type
not_equalMatches all records whose field value is not equal to the the date of the provided match value + offset_amount + relative_date_type
beforeMatches all records whose field value is before the date of the provided match value + offset_amount + relative_date_type
on_or_beforeMatches all records whose field value is before the date of the provided match value + offset_amount + relative_date_type
afterMatches all records whose field value is after the date of the provided match value + offset_amount + relative_date_type
on_or_afterMatches all records whose field value is after the date of the provided match value + offset_amount + relative_date_type
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty

Created At

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

➡️    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.

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 typeDescription
equalMatches all records whose creation date is equal to the the date of the provided match value + offset_amount + relative_date_type
not_equalMatches all records whose creation date is not equal to the the date of the provided match value + offset_amount + relative_date_type
beforeMatches all records whose creation date is before the date of the provided match value + offset_amount + relative_date_type
on_or_beforeMatches all records whose creation date is before the date of the provided match value + offset_amount + relative_date_type
afterMatches all records whose creation date is after the date of the provided match value + offset_amount + relative_date_type
on_or_afterMatches 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:

➡️    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.

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 typeDescription
equalMatches all records whose date of last modification is equal to the the date of the provided match value + offset_amount + relative_date_type
not_equalMatches all records whose date of last modification is not equal to the the date of the provided match value + offset_amount + relative_date_type
beforeMatches all records whose date of last modification is before the date of the provided match value + offset_amount + relative_date_type
on_or_beforeMatches all records whose date of last modification is before the date of the provided match value + offset_amount + relative_date_type
afterMatches all records whose date of last modification is after the date of the provided match value + offset_amount + relative_date_type
on_or_afterMatches 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:

➡️    Multi Email Filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_email",
"match_type": "fully_includes",
"values": [
{
"value": "[email protected]"
}
],
"type": "email"
}
]
}
Match typeDescription
fully_includesMatches 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_withMatches 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_withMatches 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.
containsMatches 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_containsMatches 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.
emptyMatches all records whose field value is empty. I.e. does not contain any email entry
not_emptyMatches 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:

➡️    Multi Phone Filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_phone",
"match_type": "starts_with",
"values": [
{
"value": "+49"
}
],
"type": "phone"
}
]
}
Match typeDescription
fully_includesMatches 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_withMatches 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_withMatches 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.
containsMatches 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_containsMatches 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.
emptyMatches all records whose field value is empty. I.e. does not contain any phone entry
not_emptyMatches 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:

➡️    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 typeDescription
equalMatches all records whose field value is equal to the provided match value
smallerMatches all records whose field value is smaller than the provided match value
smaller_or_equalMatches all records whose field value is smaller or equal to the provided match value
largerMatches all records whose field value is larger than the provided match value
larger_or_equalMatches all records whose field value is larger or equal to the provided match value
not_equalMatches all records whose field value does not reference the status specified by the match value. Comparison is case insensitive and spaces are ignored.
emptyMatches all records whose field value is empty
not_emptyMatches all records whose field value is not empty