v1

latestOpenAPI 3.1.0MIT2026-07-243952451019.0 KB

RefineFilter

Create Refine Filter

Create a new RefineFilter in the workspace. The criteria array must contain at least one entry. Criteria are validated against the safe-condition whitelist — unsupported attributes/clauses return 422 with a pointer to the dev community. See the Refine Filters Skill for the full reference (attributes, clauses, worked examples).

post/workspaces/{workspace_id}/refine_filters

Path parameters

workspace_idinteger required

Request body

Condition	Allowed clauses	Notes
email_address, first_name, last_name	eq, sw	Text — equals & starts_with only.
anonymous	eq, dne	Boolean-style option.
created_at, unsubscribed_at, last_activity	All standard date clauses	Indexed datetime columns.
tags.id	eq, dne, in, nin	Tag membership — must reference workspace-owned tag ids.
has_affiliate_attribution, has_active_affiliate_attribution, referred_by_affiliate	All standard clauses	Affiliate attribution lookups.
email_suppression	st, nst, eq, in	Email suppression set/not-set or membership.
received_broadcast, opened_broadcast, clicked_broadcast	eq, in	Must include a specific broadcast id.
opted_in_funnel_step, opted_in_funnel_at, opted_in_on_standalone_page	eq, in	Must include a specific funnel/step/page id.

Example request

{
  "refine_filter": {
    "name": "VIP newsletter audience",
    "filter_class": "ContactsFilter",
    "conjunction": "and",
    "criteria": [
      {
        "attribute": "tags.id",
        "clause": "in",
        "value": [
          "tag-pub-id-1",
          "tag-pub-id-2"
        ]
      },
      {
        "attribute": "purchased_products.id",
        "clause": "equals",
        "value": "prod-pub-id"
      },
      {
        "attribute": "created_at",
        "clause": "gte",
        "value": "2026-01-01T00:00:00Z"
      }
    ]
  }
}

Response

Created

idinteger

Refine Filter ID

public_idstring

Obfuscated Refine Filter ID

workspace_idinteger

ID of the workspace this filter belongs to

namestring nullable

Optional human-readable name for the filter. Must be unique within the workspace when set.

filter_classstring

The filter class. Currently always ContactsFilter.

conjunction'and' | 'or'

How the criteria are joined — and (all must match) or or (any must match).

created_atstring date-time

Created at

updated_atstring date-time

Updated at

Example response

{
  "id": 42,
  "public_id": "AbCdEf",
  "workspace_id": 5,
  "name": "VIP newsletter audience",
  "filter_class": "ContactsFilter",
  "conjunction": "and",
  "criteria": [
    {
      "attribute": "tags.id",
      "clause": "in",
      "value": [
        "tag-pub-id-1"
      ]
    },
    {
      "attribute": "created_at",
      "clause": "gte",
      "value": "2026-01-01"
    }
  ],
  "created_at": "2026-04-01T12:00:00.000Z",
  "updated_at": "2026-04-01T12:00:00.000Z"
}

v1