Buttondown logo

Filters

When filtering by tags, use the tag's ID—not its name—as the filter value. Both UUIDs and TypeIDs are accepted. Use contains to include subscribers with the tag and not_contains to exclude them. You can retrieve tag IDs from GET /v1/tags.

Buttondown's filtering schema can be used for multiple things:

Filters are fractal; they can be nested in groups, and groups can be nested in other groups. This is accomplished through a tree-like structure. Every "FilterGroup" has a "predicate" field, which is either "and" or "or", which determines how the filters and groups within the group are combined, a "groups" field, which is a list of "FilterGroup" objects (that's that recursive bit!), and a "filters" field, which are the leaf-level filters themselves.

Let's say you want a simple filter: all subscribers who have a tag whose ID is sub_tag_0j6hb7h40j6hb7h40j6hb7h40j. You can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}],
    "groups": [],
    "predicate": "and"
}

Now, let's say you want to filter for subscribers who have that tag and a tag whose ID is sub_tag_0j6hb7h40j6hb7h40j6hb7h40k. You can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}, {"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40k"}],
    "groups": [],
    "predicate": "and"
}

If you wanted to change that and to an or, you can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}, {"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40k"}],
    "groups": [],
    "predicate": "or"
}

Now, let's say you want to filter for subscribers who have the first tag or both the second tag and a third tag whose ID is sub_tag_0j6hb7h40j6hb7h40j6hb7h40m. This is where the whole nested thing comes in handy. You can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}],
    "groups": [
        {
            "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40k"}, {"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40m"}],
            "groups": [],
            "predicate": "and"
        }
    ],
    "predicate": "or"
}

You can read more about the specific filter construction in the Filter documentation.

{
    "filters": [],
    "groups": [],
    "predicate": "and"
}

Fields

filters

Type
array
Description

The leaf-level filters to apply to the audience.

groups

Type
array
Description

The nested groups to apply to the audience.

predicate

Type
string
Description

The logical operator to use when combining filters (either 'and' or 'or').