Skip to main content
Records

Filter

Use filters to choose which records of a database app a request returns.

The same filter object works in two places:

Everything on this page applies to both, except the metadata filters: a view stores only field filters. View filters lists the rules that apply to views only.

Requirements: records:read to retrieve filtered records, apps:edit and share access to the app to save filters in a view. Works with a personal access token, an OAuth access token or a user API key.

Coming from the Podio API?

Send filters as an array with one filter object and a match_type per field. Use the field ID: the slug (external_id) doesn't work here. Several category options go in one filter with any. A date range with from and to becomes within with exact_range and end_date, see Single date. Send sort_by (field ID or slug), sort_desc, limit and cursor in the query string, not in the body. There is no offset.

The filter object​

Send your filters as an array in filters. A record matches only if it matches every filter (AND). There is no OR.

Each field filter is a JSON object with these keys:

PropertyTypeDescriptionExample value
field_idinteger or stringID of the field to filter on. Required. The slug (external_id) returns a 400."1"
field_typestringType of the field, for example single_text, status or single_date. Required for view filters. Optional for filtered records, where field_id identifies the field, but send it anyway."single_text"
typestringLegacy data type that goes with the field type, for example text, status or date. Required. A filter without it returns a 400."text"
match_typestringThe operator, for example contains, equal or before. Each section below lists the operators a field type accepts."contains"
valuesarrayThe operands, as { "value": … } objects. Leave it out for empty and not_empty.[{ "value": "John" }]

Some field types accept more optional keys, for example for relative dates, weekdays, the "@me" flag or task list entries. See Operand keys.

This example matches all records whose field 1 contains the text "John" and whose status field 2 is set to option 123:

Combined 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"
}
]
}

Send this body to POST /v1/record/filter/app/{app_id}. Every field in a record or in Retrieve a single app carries its field_id and field_type. Category and status fields list their option IDs there, in config.settings.options.

Sort and page in the query string with sort_by, sort_desc, limit and cursor, see Pagination. To filter by creation date, last change or record number without a field, use the metadata filters.

Single text​

Use this filter for Single line text fields (single_text).

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

General behavior

  • contains, not_contains, starts_with and ends_with ignore case.
  • equal and not_equal are exact matches and case-sensitive.
  • Every operator trims leading and trailing whitespace from the match value.
  • empty and not_empty take no values.

Match types

Match typeDescription
equalMatches all records whose field value is equal to the match value.
not_equalMatches all records whose field value is not equal to the match value.
containsMatches all records whose field value contains the match value.
not_containsMatches all records whose field value does not contain the match value.
starts_withMatches all records whose field value starts with the match value.
ends_withMatches all records whose field value ends with the match value.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Multi text​

Use this filter for Multi line text fields (multi_text).

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

General behavior

  • The filter matches against the unformatted (plain text) value of the field.
  • contains, not_contains, starts_with and ends_with ignore case.
  • equal and not_equal are exact matches and case-sensitive.
  • Every operator trims leading and trailing whitespace.
  • empty and not_empty take no values.

Match types

Match typeDescription
equalMatches all records whose unformatted field value is equal to the match value.
not_equalMatches all records whose unformatted field value is not equal to the match value.
containsMatches all records whose unformatted field value contains the match value.
not_containsMatches all records whose unformatted field value does not contain the match value.
starts_withMatches all records whose unformatted field value starts with the match value.
ends_withMatches all records whose unformatted field value ends with the match value.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Number​

Use this filter for Number fields (number).

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

Send the number to compare against as a bare numeric value in values[0].value. Leave out values for empty and not_empty.

Match types

Match typeDescription
equalMatches all records whose field value is equal to the provided match value.
not_equalMatches all records whose field value is not 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 than or equal to the 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 than or equal to the match value.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Unique ID​

Use this filter for Unique ID fields (unique_id).

Unique ID filter
{
"filters": [
{
"field_id": "1",
"field_type": "unique_id",
"match_type": "larger_or_equal",
"values": [{ "value": 1000 }],
"type": "number"
}
]
}

A Unique ID field shows the record number Tape counts up per database app. This is the record's app_record_id: the first record in a database app is 1, the second 2, and so on.

General behavior

  • Send the match value as a bare number without a prefix.
  • The filter compares the underlying number, so type is "number", not "unique_id".
  • Leave out values for empty and not_empty.
  • Every record has a record number. empty matches no records, and not_empty matches every record.
Your database app has no Unique ID field?

Use the app_record_id metadata filter. It filters on the same number without a field.

Match types

The match types are the same as for number:

Match typeDescription
equalMatches the record whose number is equal to the provided match value.
not_equalMatches all records whose number is not equal to the provided match value.
smallerMatches all records whose number is smaller than the provided match value.
smaller_or_equalMatches all records whose number is smaller than or equal to the provided match value.
largerMatches all records whose number is larger than the provided match value.
larger_or_equalMatches all records whose number is larger than or equal to the provided match value.
emptyMatches no records, because every record has a number.
not_emptyMatches every record.

Single category​

Use this filter for Single select fields (single_category).

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

General behavior

  • Send the numeric ID of an option or its label as the match value.
  • Label matching ignores case and leading and trailing whitespace.
  • A label that matches more than one option returns an error. Use the option ID instead.
  • equal takes exactly one option. More than one returns a 400. Use any for several options.
  • When you read the filter back, operands come as option IDs.
  • empty and not_empty take no values.

Match types

Match typeDescription
equalMatches all records whose field value references the option specified.
not_equalMatches all records whose field value does not reference the option specified.
anyMatches all records whose field value references any of the options specified.
noneMatches all records whose field value references none of the options specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Multi category​

Use this filter for Multiple select fields (multi_category).

Multi category filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_category",
"match_type": "contains",
"values": [{ "value": 1 }, { "value": "Not Started" }],
"type": "category"
}
]
}

A multi_category field holds a set of options, so the match types compare sets:

  • equal needs exactly the given options. Order doesn't matter.
  • contains needs all given options. The field may hold more.
  • any and none test for overlap with the given options.

General behavior

  • Send the numeric ID of an option or its label.
  • Label matching ignores case and leading and trailing whitespace.
  • An ambiguous label returns an error. Use the option ID instead.
  • When you read the filter back, operands come as option IDs.
  • empty and not_empty take no values.

Match types

Match typeDescription
equalMatches all records whose field value references exactly the options specified and no others.
containsMatches all records whose field value references all of the options specified (and may reference more).
anyMatches all records whose field value references at least one of the options specified.
noneMatches all records whose field value references none of the options specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Status​

Use this filter for Status fields (status).

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

General behavior

  • Send the numeric ID of a status option or its label.
  • Label matching ignores case and leading and trailing whitespace.
  • An ambiguous label returns an error. Use the option ID instead.
  • When you read the filter back, operands come as option IDs.
  • completed, incomplete, empty and not_empty take no values.
  • completed and incomplete test whether the status option the record has is marked as completed.

Match types

Match typeDescription
equalMatches all records whose field value references the status option specified.
not_equalMatches all records whose field value does not reference the status option specified.
anyMatches all records whose field value references any of the status options specified.
noneMatches all records whose field value references none of the status options specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.
completedMatches all records whose referenced status option is marked as completed.
incompleteMatches all records whose referenced status option is not marked as completed.

Single relation​

Use this filter for Relation fields that hold one record (single_relation).

Single relation filter
{
"filters": [
{
"field_id": "1",
"field_type": "single_relation",
"match_type": "any",
"values": [{ "value": 1 }],
"type": "app"
}
]
}

Send the IDs of the related records as match values. When you read the filter back, operands come as record IDs. empty and not_empty take no values.

Match types

Match typeDescription
equalMatches all records whose field value references the record specified.
not_equalMatches all records whose field value does not reference the record specified.
anyMatches all records whose field value references any of the records specified.
noneMatches all records whose field value references none of the records specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Multi relation​

Use this filter for Relation fields that hold several records (multi_relation).

Multi relation filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_relation",
"match_type": "contains",
"values": [{ "value": 1 }, { "value": 2 }],
"type": "app"
}
]
}

A multi_relation field holds a set of related records, so the match types compare sets:

  • equal needs exactly the given records. Order doesn't matter.
  • contains needs all given records. The field may hold more.
  • any and none test for overlap.

Send the IDs of the related records as match values. When you read the filter back, operands come as record IDs. empty and not_empty take no values.

Match types

Match typeDescription
equalMatches all records whose field value references exactly the records specified and no others.
containsMatches all records whose field value references all of the records specified (and may reference more).
anyMatches all records whose field value references at least one of the records specified.
noneMatches all records whose field value references none of the records specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Single user​

Use this filter for Member fields that hold one member (single_user).

Single user filter
{
"filters": [
{
"field_id": "1",
"field_type": "single_user",
"match_type": "any",
"values": [{ "value": 1 }],
"type": "contact"
}
]
}

General behavior

  • Send the user IDs to filter by. Retrieve organization users lists them.
  • To add yourself, set include_active_user (the "@me" reference). See Operand keys.
  • When you read the filter back, operands come as user IDs.
  • empty and not_empty take no values and don't work with include_active_user.

Match types

Match typeDescription
equalMatches all records whose field value references the user specified.
not_equalMatches all records whose field value does not reference the user specified.
anyMatches all records whose field value references any of the users specified.
noneMatches all records whose field value references none of the users specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Multi user​

Use this filter for Member fields that hold several members (multi_user).

Multi user filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_user",
"match_type": "contains",
"values": [{ "value": 1 }, { "value": 2 }],
"type": "contact"
}
]
}

A multi_user field holds a set of users, so the match types compare sets:

  • equal needs exactly the given users. Order doesn't matter.
  • contains needs all given users. The field may hold more.
  • any and none test for overlap.

General behavior

  • Send the user IDs to filter by.
  • To add yourself, set include_active_user (the "@me" reference). See Operand keys.
  • When you read the filter back, operands come as user IDs.
  • empty and not_empty take no values and don't work with include_active_user.

Match types

Match typeDescription
equalMatches all records whose field value references exactly the users specified and no others.
containsMatches all records whose field value references all of the users specified (and may reference more).
anyMatches all records whose field value references at least one of the users specified.
noneMatches all records whose field value references none of the users specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Created by​

Use this filter for Created by fields (created_by). The field holds the user who created the record.

Created by filter
{
"filters": [
{
"field_id": "1",
"field_type": "created_by",
"match_type": "any",
"values": [{ "value": 1 }],
"type": "contact"
}
]
}

General behavior

  • Send the user IDs to filter by.
  • To add yourself, set include_active_user (the "@me" reference). See Operand keys. any with include_active_user selects the records you created.
  • When you read the filter back, operands come as user IDs.
  • The type is contact, as for a user field. It's not created_by.
  • empty and not_empty take no values and don't work with include_active_user.

Match types

Match typeDescription
equalMatches all records created by the user specified.
not_equalMatches all records not created by the user specified.
anyMatches all records created by any of the users specified.
noneMatches all records created by none of the users specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Last modified by​

Use this filter for Last edited by fields (last_modified_by). The field holds the user who last changed the record.

Last modified by filter
{
"filters": [
{
"field_id": "1",
"field_type": "last_modified_by",
"match_type": "any",
"values": [{ "value": 1 }],
"type": "contact"
}
]
}

General behavior

  • Send the user IDs to filter by.
  • To add yourself, set include_active_user (the "@me" reference). See Operand keys. any with include_active_user selects the records you changed last.
  • When you read the filter back, operands come as user IDs.
  • The type is contact, as for a user field. It's not last_modified_by.
  • empty and not_empty take no values and don't work with include_active_user.

Match types

Match typeDescription
equalMatches all records last modified by the user specified.
not_equalMatches all records not last modified by the user specified.
anyMatches all records last modified by any of the users specified.
noneMatches all records last modified by none of the users specified.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Single date​

Use this filter for Date fields with one date (single_date).

Single date filter
{
"filters": [
{
"field_id": "1",
"field_type": "single_date",
"match_type": "before",
"relative_date_type": "exact_date",
"values": [{ "value": { "date": "2020-01-01T00:00:00.000Z" } }],
"type": "date"
}
]
}

Put the target date in the nested values[0].value.date as an ISO 8601 string. A bare value (values[0].value: "2020-01-01") also works on input, but a GET returns the nested form, which you can send back unchanged. Leave out values for empty and not_empty.

Tape resolves the date to match from values[0].value.date, the relative_date_type and, for the num_days_*, num_weeks_* and num_months_* types, values[0].value.offset_amount. For example, num_days_before with an offset of 1 and a date of 2020-01-01 resolves to 2019-12-31. today, tomorrow and yesterday need no value (all values).

Four operators select a period instead of a single day. Each reads its own operand key (values under Operand keys):

  • within pairs with relative_date_range_type and matches a named or bounded range, for example current_week, past_num_days or exact_range. For exact_range, send the start in values[0].value.date and the end in the top-level end_date. For next_num_days and past_num_days, send the count in offset_amount.
  • on_weekday pairs with weekday (monday to sunday).
  • in_quarter_of_year pairs with quarter_of_year (q1 to q4).
  • in_month_of_year pairs with month_of_year (january to december).
Does a date filter include the target day?

Tape expands the date to a full day, from start of day to end of day in your timezone. The time of day in the value doesn't count. So not all boundary operators include the day:

  • before matches strictly before the start of the target day. The day itself is excluded.
  • after matches strictly after the end of the target day. The day itself is excluded.
  • on_or_before includes the whole day up to its end.
  • on_or_after includes the whole day from its start.
  • equal matches the whole target day. not_equal matches everything outside it.

Match types

Match typeDescription
equalMatches all records whose field date falls on the target day.
not_equalMatches all records whose field date does not fall on the target day.
beforeMatches all records whose field date is before the start of the target day (day excluded).
on_or_beforeMatches all records whose field date is on or before the target day (whole day included).
afterMatches all records whose field date is after the end of the target day (day excluded).
on_or_afterMatches all records whose field date is on or after the target day (whole day included).
withinMatches all records whose field date falls within the range selected by relative_date_range_type.
on_weekdayMatches all records whose field date falls on the supplied weekday.
in_quarter_of_yearMatches all records whose field date falls in the supplied quarter_of_year.
in_month_of_yearMatches all records whose field date falls in the supplied month_of_year.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Range date​

Use this filter for Date fields with a start and an end date (range_date).

Range date filter
{
"filters": [
{
"field_id": "1",
"field_type": "range_date",
"match_type": "within",
"relative_date_range_type": "exact_range",
"values": [{ "value": { "date": "2020-01-01T00:00:00.000Z" } }],
"end_date": "2020-12-31T00:00:00.000Z",
"type": "date"
}
]
}

The field stores a start and an end date. Operands and operand keys are the same as for Single date. Leave out values for empty and not_empty.

The typical combination is within with relative_date_range_type: "exact_range". It tests the stored range against a window from values[0].value.date (start) to the top-level end_date (end).

How do range operators compare dates?

Tape expands each date to a full day, from start of day to end of day in your timezone. The time of day doesn't count. Each operator then tests the stored [start, end] interval against the target day or window:

  • equal and within match any range that overlaps it, not only ranges that equal it or sit inside it.
  • before, after, on_or_before and on_or_after compare the ends of the range with the day boundary.

Match types

Match typeDescription
equalMatches all records whose range overlaps the target day.
not_equalMatches all records whose range does not overlap the target day.
beforeMatches all records whose range starts before the start of the target day.
on_or_beforeMatches all records whose range falls on or before the target day.
afterMatches all records whose range falls after the end of the target day.
on_or_afterMatches all records whose range falls on or after the target day.
withinMatches all records whose range overlaps the range selected by relative_date_range_type.
on_weekdayMatches all records whose range falls on the supplied weekday.
in_quarter_of_yearMatches all records whose range falls in the supplied quarter_of_year.
in_month_of_yearMatches all records whose range falls in the supplied month_of_year.
emptyMatches all records whose field value is empty.
not_emptyMatches all records whose field value is not empty.

Created at​

Use this filter for Created on fields (created_on). It filters by the creation date of the record.

Your database app has no Created on field?

Use the created_at metadata filter. It works in every database app, with or without the field.

Created at filter
{
"filters": [
{
"field_id": "1",
"field_type": "created_on",
"match_type": "on_or_after",
"relative_date_type": "exact_date",
"values": [{ "value": { "date": "2020-01-01T00:00:00.000Z" } }],
"type": "date"
}
]
}

The field_type is created_on, and the type is date. Operands, operators and operand keys are the same as for Single date. Leave out values for empty and not_empty.

Need exact timestamps?

Tape ignores the time of day and expands the date to a full day in your timezone. before and after exclude that day, on_or_before and on_or_after include it. The created_at metadata filter compares exact timestamps and includes the bound for all four operators.

Match types

Match typeDescription
equalMatches all records whose creation date falls on the target day.
not_equalMatches all records whose creation date does not fall on the target day.
beforeMatches all records created before the start of the target day (day excluded).
on_or_beforeMatches all records created on or before the target day (whole day included).
afterMatches all records created after the end of the target day (day excluded).
on_or_afterMatches all records created on or after the target day (whole day included).
withinMatches all records whose creation date falls within the range selected by relative_date_range_type.
on_weekdayMatches all records whose creation date falls on the supplied weekday.
in_quarter_of_yearMatches all records whose creation date falls in the supplied quarter_of_year.
in_month_of_yearMatches all records whose creation date falls in the supplied month_of_year.
emptyMatches all records with no creation date.
not_emptyMatches all records that have a creation date.

Last modified at​

Use this filter for Last edited on fields (last_modified_on). It filters by the date of the last change to the record.

Your database app has no Last edited on field?

Use the last_modified_at metadata filter. It works in every database app, with or without the field.

Last modified at filter
{
"filters": [
{
"field_id": "1",
"field_type": "last_modified_on",
"match_type": "on_or_after",
"relative_date_type": "num_weeks_before",
"values": [{ "value": { "offset_amount": 1 } }],
"type": "date"
}
]
}

The field_type is last_modified_on, and the type is date. In the example, num_weeks_before with offset_amount: 1 resolves to one week ago. Operands, operators and operand keys are the same as for Single date. Leave out values for empty and not_empty.

Need exact timestamps?

Tape ignores the time of day and expands the date to a full day in your timezone. before and after exclude that day, on_or_before and on_or_after include it. The last_modified_at metadata filter compares exact timestamps and includes the bound for all four operators.

Match types

Match typeDescription
equalMatches all records whose last-modified date falls on the target day.
not_equalMatches all records whose last-modified date does not fall on the target day.
beforeMatches all records last modified before the start of the target day (day excluded).
on_or_beforeMatches all records last modified on or before the target day (whole day included).
afterMatches all records last modified after the end of the target day (day excluded).
on_or_afterMatches all records last modified on or after the target day (whole day included).
withinMatches all records whose last-modified date falls within the range selected by relative_date_range_type.
on_weekdayMatches all records whose last-modified date falls on the supplied weekday.
in_quarter_of_yearMatches all records whose last-modified date falls in the supplied quarter_of_year.
in_month_of_yearMatches all records whose last-modified date falls in the supplied month_of_year.
emptyMatches all records with no last-modified date.
not_emptyMatches all records that have a last-modified date.

Calculation​

Use this filter for Calculation fields (calculation).

Calculation filter
{
"filters": [
{
"field_id": "1",
"field_type": "calculation",
"match_type": "smaller",
"values": [{ "value": 12.34 }],
"type": "calculation"
}
]
}

A calculation field returns a text, a number or a date, depending on its script. The result type decides which match types make sense. Send the same operand as for the matching field type:

  • Number result: use the number operators with a bare number in values[0].value, as for a Number field.
  • Text result: use the text operators with a string in values[0].value, as for a Single text field.
  • Date result: use the date operators with the nested values[0].value.date (with optional offset_amount) and the date operand keys, as for a Single date field (see Operand keys).

General behavior

  • empty and not_empty work for every result type. Leave out values.
  • within, on_weekday, in_quarter_of_year and in_month_of_year work only when the calculation returns a date.
  • The relative dates today, tomorrow and yesterday work only when the calculation returns a date.
  • Using a date-only operator on a text or number calculation returns a 400.
  • A text operator on a number calculation, for example contains, returns a 500 with unknown. The date comparisons before, after, on_or_before and on_or_after can do the same. Use only the operators of the result type.

Match types

The table lists the match types of all result types together.

Match typeApplies toDescription
emptyanyMatches all records whose field value is empty.
not_emptyanyMatches all records whose field value is not empty.
equalnumber, text, dateMatches all records whose field value is equal to the provided match value (day-granular for a date result).
not_equalnumber, text, dateMatches all records whose field value is not equal to the provided match value.
smallernumberMatches all records whose field value is smaller than the provided match value.
smaller_or_equalnumberMatches all records whose field value is smaller than or equal to the match value.
largernumberMatches all records whose field value is larger than the provided match value.
larger_or_equalnumberMatches all records whose field value is larger than or equal to the match value.
containstextMatches all records whose field value contains the provided match value.
not_containstextMatches all records whose field value does not contain the provided match value.
starts_withtextMatches all records whose field value starts with the provided match value.
ends_withtextMatches all records whose field value ends with the provided match value.
beforedateMatches all records whose field date is before the start of the target day (day excluded).
on_or_beforedateMatches all records whose field date is on or before the target day (whole day included).
afterdateMatches all records whose field date is after the end of the target day (day excluded).
on_or_afterdateMatches all records whose field date is on or after the target day (whole day included).
withindateMatches all records whose field date falls within the range selected by relative_date_range_type.
on_weekdaydateMatches all records whose field date falls on the supplied weekday.
in_quarter_of_yeardateMatches all records whose field date falls in the supplied quarter_of_year.
in_month_of_yeardateMatches all records whose field date falls in the supplied month_of_year.

Multi email​

Use this filter for Email fields (multi_email).

Multi email filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_email",
"match_type": "fully_includes",
"values": [{ "value": "juliet@acme.com" }],
"type": "email"
}
]
}

General behavior

  • An email field can hold several addresses. A record matches when at least one address meets the condition.
  • not_contains matches when no address contains the value. empty matches when there are no addresses.
  • Matching ignores case and leading and trailing whitespace in the match value.

Match types

Match typeDescription
fully_includesMatches records that have at least one email entry equal to the match value in full.
containsMatches records that have at least one email entry containing the match value.
not_containsMatches records where none of the email entries contain the match value.
starts_withMatches records that have at least one email entry starting with the match value.
ends_withMatches records that have at least one email entry ending with the match value.
emptyMatches records whose field value is empty (no email entries). Omit values.
not_emptyMatches records whose field value is not empty (at least one email entry). Omit values.

Multi phone​

Use this filter for Phone fields (multi_phone).

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

General behavior

  • A phone field can hold several numbers. A record matches when at least one number meets the condition.
  • not_contains matches when no number contains the value. empty matches when there are no numbers.
  • Matching ignores case and leading and trailing whitespace in the match value.

Match types

Match typeDescription
fully_includesMatches records that have at least one phone entry equal to the match value in full.
containsMatches records that have at least one phone entry containing the match value.
not_containsMatches records where none of the phone entries contain the match value.
starts_withMatches records that have at least one phone entry starting with the match value.
ends_withMatches records that have at least one phone entry ending with the match value.
emptyMatches records whose field value is empty (no phone entries). Omit values.
not_emptyMatches records whose field value is not empty (at least one phone entry). Omit values.

Use this filter for Link fields (multi_link).

Multi link filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_link",
"match_type": "contains",
"values": [{ "value": "github.com" }],
"type": "embed"
}
]
}

General behavior

  • The type for a link field is embed, not link.
  • A link field can hold several links. The filter matches the URL of each link and ignores case and surrounding whitespace.
  • A record matches when at least one URL meets the condition.
  • Link fields have no exact match. equal and fully_includes return a 400. Use contains, starts_with or ends_with instead.

Match types

Match typeDescription
containsMatches records that have at least one link whose URL contains the match value.
not_containsMatches records where none of the link URLs contain the match value.
starts_withMatches records that have at least one link whose URL starts with the match value.
ends_withMatches records that have at least one link whose URL ends with the match value.
emptyMatches records whose field value is empty (no links). Omit values.
not_emptyMatches records whose field value is not empty (at least one link). Omit values.

Single location​

Use this filter for Location fields (single_location).

Single location filter
{
"filters": [
{
"field_id": "1",
"field_type": "single_location",
"match_type": "contains",
"values": [{ "value": "Berlin" }],
"type": "location"
}
]
}

General behavior

  • The filter matches free text in the formatted address. This is street address, postal code, city, state, country and the original formatted address, joined together.
  • You can't filter on a single part, such as the city or the country alone.
  • Matching ignores case and leading and trailing whitespace in the match value.

Match types

Match typeDescription
containsMatches records whose formatted address contains the match value.
not_containsMatches records whose formatted address does not contain the match value (records with no address set also match).
emptyMatches records whose field value is empty (no address set). A coordinate-only value counts as not empty. Omit values.
not_emptyMatches records whose field value is not empty (an address or coordinates are set). Omit values.

Single attachment​

Use this filter for Files fields that hold one file (single_attachment).

Single attachment filter
{
"filters": [
{
"field_id": "1",
"field_type": "single_attachment",
"match_type": "contains",
"values": [{ "value": "invoice" }],
"type": "file"
}
]
}

General behavior

  • The type for an attachment field is file.
  • The filter matches the file name, never the file ID. Send the match value as a string.
  • Matching ignores case and leading and trailing whitespace in the match value.

Match types

Match typeDescription
equalMatches records whose attached file name equals the match value.
not_equalMatches records whose attached file name does not equal the match value.
containsMatches records whose attached file name contains the match value.
not_containsMatches records whose attached file name does not contain the match value.
starts_withMatches records whose attached file name starts with the match value.
ends_withMatches records whose attached file name ends with the match value.
emptyMatches records with no file attached. Omit values.
not_emptyMatches records with a file attached. Omit values.

Multi attachment​

Use this filter for Files fields that hold several files (multi_attachment).

Multi attachment filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_attachment",
"match_type": "contains",
"values": [{ "value": "invoice" }],
"type": "file"
}
]
}

General behavior

  • As for Single attachment, the type is file and the filter matches file names. Send a string.
  • The field can hold several files, so every match type checks all of them.
  • equal and not_equal compare the match value with each file name exactly.

Match types

Match typeDescription
equalMatches records where at least one attached file name equals the match value.
not_equalMatches records where no attached file name equals the match value (records with no attachments also match).
containsMatches records where an attached file name contains the match value.
not_containsMatches records where none of the attached file names contain the match value.
starts_withMatches records where at least one attached file name starts with the match value.
ends_withMatches records where at least one attached file name ends with the match value.
emptyMatches records with no files attached. Omit values.
not_emptyMatches records with at least one file attached. Omit values.

Multi image​

Use this filter for Image fields (multi_image).

Multi image filter
{
"filters": [
{
"field_id": "1",
"field_type": "multi_image",
"match_type": "ends_with",
"values": [{ "value": ".png" }],
"type": "file"
}
]
}

General behavior

  • Image fields share the type file with attachment fields. field_type tells them apart.
  • The filter matches the image file name. Send a string.
  • The field can hold several images, so every match type checks all of them. equal and not_equal compare the match value with each file name exactly.
  • Matching ignores case and leading and trailing whitespace in the match value.

Match types

Match typeDescription
equalMatches records where at least one image file name equals the match value.
not_equalMatches records where no image file name equals the match value (records with no images also match).
containsMatches records where an image file name contains the match value.
not_containsMatches records where none of the image file names contain the match value.
starts_withMatches records where at least one image file name starts with the match value.
ends_withMatches records where at least one image file name ends with the match value.
emptyMatches records with no images. Omit values.
not_emptyMatches records with at least one image. Omit values.

Checklist​

Use this filter for Task list fields (checklist). Choose the entry property to filter on with entry_property: title, assignee, status or due_date.

Task list filter
{
"filters": [
{
"field_id": "1",
"field_type": "checklist",
"entry_property": "title",
"match_type": "contains",
"values": [{ "value": "Design review" }],
"type": "checklist"
}
]
}

A task list holds entries (subtasks in Tape). Each entry has a title, an optional assignee, a completion status and an optional due date. Every match type checks all entries: title with contains matches a record when any entry title contains the value.

Without entry_property, the filter applies to the whole field and supports only empty and not_empty: the task list has no entries, or at least one entry.

The type is checklist for every task list filter. This table shows the match types and the operand for each entry_property. Any other combination returns a 400.

entry_propertyAllowed match_typeOperand
(omitted)empty, not_emptynone, leave out values
titlecontains, not_contains, empty, not_emptyvalues: [{ "value": "<text>" }] (a string); leave out values for empty / not_empty
assigneeequal, not_equal, empty, not_emptyvalues: [{ "value": <user_id> }, …] (one or more user IDs) and/or include_active_user: true; leave out values for empty / not_empty
statusequalvalues: [{ "value": <boolean> }]: true = completed, false = incomplete
due_dateequal, not_equal, empty, not_empty, before, after, on_or_before, on_or_after, withina date operand, see Operand keys; leave out values for empty / not_empty

General behavior

  • status uses a boolean, not a match type. The Status field uses the match types completed and incomplete. A task list status filter uses match_type: "equal" with a boolean: false for incomplete entries, true for completed entries.
  • include_active_user works only for the assignee. Use the "@me" flag include_active_user: true only with entry_property: "assignee", and only with equal or not_equal, not with empty or not_empty. See Operand keys.
  • due_date has no exact_range. within needs a relative_date_range_type. Unlike date fields, task lists don't support exact_range, because there is no exact end date to store. Use a bounded range such as next_num_days or current_week.

Example: incomplete entries (status with a boolean value)

Task list filter: incomplete entries
{
"filters": [
{
"field_id": "1",
"field_type": "checklist",
"entry_property": "status",
"match_type": "equal",
"values": [{ "value": false }],
"type": "checklist"
}
]
}

Example: due within the next 7 days (due_date with within and a relative range)

Task list filter: due within the next 7 days
{
"filters": [
{
"field_id": "1",
"field_type": "checklist",
"entry_property": "due_date",
"match_type": "within",
"relative_date_range_type": "next_num_days",
"values": [{ "value": { "offset_amount": 7 } }],
"type": "checklist"
}
]
}

Example: assigned to me (assignee with include_active_user)

Task list filter: assigned to me
{
"filters": [
{
"field_id": "1",
"field_type": "checklist",
"entry_property": "assignee",
"match_type": "equal",
"include_active_user": true,
"type": "checklist"
}
]
}

Match types

Match typeValid entry_propertyDescription
equalassignee, status, due_dateAn entry matches the operand: assigned to the given user / completion equals the boolean / due date equals the date.
not_equalassignee, due_dateNegation of equal.
containstitleAn entry title contains the match value.
not_containstitleNo entry title contains the match value.
empty(omitted), title, assignee, due_dateField level: the task list has no entries. Entry level: the title, assignee or due date of an entry is empty. Omit values.
not_empty(omitted), title, assignee, due_dateComplement of empty. Omit values.
beforedue_dateAn entry's due date is before the resolved date.
afterdue_dateAn entry's due date is after the resolved date.
on_or_beforedue_dateAn entry's due date is on or before the resolved date.
on_or_afterdue_dateAn entry's due date is on or after the resolved date.
withindue_dateAn entry's due date falls within the given range. Requires relative_date_range_type.

Operand keys​

Operand keys are optional properties next to values that refine the condition. Most apply to date filters: Single date, Range date, Created at, Last modified at, calculations that return a date, and task list due_date filters.

Use each key only with the field types listed below. Tape ignores a key that doesn't fit, without an error: weekday on a text filter changes nothing.

Where does offset_amount go?

All operand keys below are top-level properties of the filter object, except offset_amount. It goes inside the value at values[0].value.offset_amount. At the top level, Tape ignores it, so a num_days_before filter with only a top-level offset_amount returns a 400.

Operand keyWhere it goesApplies toUsed with
relative_date_typetop-leveldate filters, checklist due_dateresolves the target date for a comparison
relative_date_range_typetop-leveldate filters, checklist due_datematch_type: within
end_datetop-leveldate filterswithin with relative_date_range_type: exact_range
weekdaytop-leveldate filtersmatch_type: on_weekday
quarter_of_yeartop-leveldate filtersmatch_type: in_quarter_of_year
month_of_yeartop-leveldate filtersmatch_type: in_month_of_year
include_active_usertop-leveluser filters, checklist assigneeboolean "@me" flag
entry_propertytop-levelchecklistselects the entry sub-property
offset_amountnested in values[0].valuedate filters, checklist due_datethe num_* / next_num_days / past_num_days types

relative_date_type​

Resolves a comparison (equal, before, after, on_or_before, on_or_after and so on) to a single date. Supported values:

relative_date_typeValue to provideMeaning
today, tomorrow, yesterdaynonethe corresponding day
exact_datevalues[0].value.date (ISO-8601 string)an absolute calendar date
num_days_before, num_days_aftervalues[0].value.offset_amount (integer)N days before / after
num_weeks_before, num_weeks_aftervalues[0].value.offset_amount (integer)N weeks before / after
num_months_before, num_months_aftervalues[0].value.offset_amount (integer)N months before / after

General behavior

  • For single_date and range_date fields, Tape applies the num_* offset to the date in values[0].value.date.
  • For created_on, last_modified_on and task list due_date filters, Tape applies the offset to the current date and ignores any date you send.
  • exact_date accepts only an ISO 8601 string. A numeric epoch doesn't work. end_date accepts an epoch number.

relative_date_range_type​

Selects a date range for match_type: within. Supported values:

relative_date_range_typeValue to provide
current_week, current_month, current_year, past_week, past_month, past_year, next_week, next_month, next_yearnone
next_num_days, past_num_daysvalues[0].value.offset_amount (integer)
exact_rangevalues[0].value.date (start) and end_date (end)

exact_range works only on date fields. Task list due_date filters support every value except exact_range.

end_date​

The end of the range for a within filter with exact_range on a date field. Send an ISO date string or an epoch number. The start of the range comes from values[0].value.date.

weekday​

One of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Use it with match_type: on_weekday on date fields to match records whose date falls on this weekday.

quarter_of_year​

One of q1, q2, q3, q4. Use it with match_type: in_quarter_of_year on date fields.

month_of_year​

One of january, february, march, april, may, june, july, august, september, october, november, december. Use it with match_type: in_month_of_year on date fields.

include_active_user​

A boolean "@me" flag for the user your credential belongs to. Set include_active_user: true to match that user without a fixed user ID.

  • It works with user filters (single_user, multi_user, created_by, last_modified_by) and with task list assignee filters.
  • For a task list, it works only with entry_property: "assignee" and only with equal or not_equal, not with empty or not_empty.
  • You can combine it with user IDs in values.

entry_property​

Only for task lists: the entry property the filter applies to (title, assignee, status or due_date). Without it, the filter applies to the whole field and supports only empty and not_empty (see Checklist).

offset_amount​

An integer inside the value object at values[0].value.offset_amount, not a top-level key. It gives the count for the num_days_*, num_weeks_* and num_months_* relative date types and for the next_num_days and past_num_days range types.

Record metadata filters​

Metadata filters match properties every record has, so they need no field in the database app. Set only type and leave out field_id and field_type:

typeFilters onMatch value
created_atWhen the record was creatednested, { "date": "…" }
last_modified_atWhen the record was last modifiednested, { "date": "…" }
app_record_idThe app-specific ID of the record (the app_record_id property)bare value, for example 123

Put metadata filters in the same filters array as field filters. They combine with the same AND.

Where does the timestamp match value go?

created_at and last_modified_at read the match value from values[0].value.date, a nested object. Field filters and app_record_id use a bare value at values[0].value.

Created at (metadata)​

Use this filter to find records by creation time, without a Created on field in the database app.

Created at metadata filter: bounded window
{
"filters": [
{
"type": "created_at",
"match_type": "on_or_after",
"values": [{ "value": { "date": "2026-07-01T00:00:00.000Z" } }]
},
{
"type": "created_at",
"match_type": "on_or_before",
"values": [{ "value": { "date": "2026-07-02T00:00:00.000Z" } }]
}
]
}

General behavior

  • Absolute UTC dates only. Send a full ISO 8601 timestamp as value.date. Leave out relative_date_type or set it to exact_date. A relative value such as num_days_before or num_weeks_after returns a 400. Tape accepts offset_amount but ignores it. Don't rely on it.
  • All bounds are inclusive. Every match type compares with >= or <=. after works like on_or_after, and before like on_or_before.
  • Use two filters for a window: one lower bound and one upper bound, as in the example. Repeating a bound in the same direction narrows the window: the latest lower bound and the earliest upper bound win. It never widens it.
  • Invalid input returns a 400 instead of being dropped: an unsupported match_type, a missing or unreadable date, or a year outside 1 to 9999.

Match types

Match typeDescription
after, on_or_after, larger, larger_or_equalMatches records created on or after the value.
before, on_or_before, smaller, smaller_or_equalMatches records created on or before the value.

Any other match type (equal, empty, not_empty and so on) returns a 400.

For a database app with a Created on field, see Created at.

Last modified at (metadata)​

Use this filter to find records by the time of their last change. It works like Created at (metadata) in every respect: same match types, inclusive bounds, absolute dates only and the same 400 behavior. Use type: "last_modified_at".

Last modified at metadata filter
{
"filters": [
{
"type": "last_modified_at",
"match_type": "on_or_after",
"values": [{ "value": { "date": "2026-07-01T00:00:00.000Z" } }]
}
]
}
Why don't unedited records match?

A record nobody edited after creating it has no last-modified timestamp, so no last_modified_at filter matches it. To get everything created or modified since a point in time, merge two requests as in Pattern: incremental sync.

App record ID (metadata)​

Use this filter to find records by their app-specific ID. This is the sequential app_record_id every record returns: the first record in a database app is 1, the second 2, and so on.

App record ID metadata filter
{
"filters": [
{
"type": "app_record_id",
"match_type": "larger_or_equal",
"values": [{ "value": 1000 }]
}
]
}

General behavior

  • The match value is a bare value at values[0].value, not a nested object.
  • The value must be a number. A missing or non-numeric value returns a 400 for every match type, including empty and not_empty.
  • Any match type not in the table returns a 400.
  • Every record has an app_record_id. empty matches nothing, and not_empty matches every record.

Match types

Match typeDescription
equalMatches the record whose app_record_id equals the value.
not_equalMatches all records whose app_record_id does not equal the value.
largerMatches all records whose app_record_id is larger than the value.
larger_or_equalMatches all records whose app_record_id is larger than or equal to the value.
smallerMatches all records whose app_record_id is smaller than the value.
smaller_or_equalMatches all records whose app_record_id is smaller than or equal to the value.
emptyMatches no records, because every record has an app_record_id.
not_emptyMatches every record.

Pattern: incremental sync​

Use the timestamp metadata filters to get only the records that changed since your last run. You don't need Created on or Last edited on fields.

Filters have no OR, so "created or modified since T" takes two requests:

Request 1: records created since T
{
"filters": [
{
"type": "created_at",
"match_type": "on_or_after",
"values": [{ "value": { "date": "2026-07-22T00:00:00.000Z" } }]
}
]
}

Merge the results and remove duplicates by record_id. Request 2 misses records nobody edited after creation. Request 1 catches them.

Why does my sync return fewer records now?

Earlier, the API accepted the created_at and last_modified_at metadata filters but ignored them and returned all records. Now it applies them, so an integration that relied on the old behavior gets fewer records.

Next steps​