v1

latestOpenAPI 3.1.0MIT2026-07-243952451019.0 KB

Contacts::Filter

Generate a Contact Filter

Translates a natural-language audience description into a ClickFunnels contact filter using an AI model.

The response always includes the same key set: a stable_id token, a structured filter object, and the identity fields id, public_id, workspace_id, and name. When save: true is supplied the filter is persisted as a reusable Refine::StoredFilter and those identity fields are populated; otherwise they are null. A saved filter can be fetched later via GET /api/v2/contacts/filters/{id}.

Pass the returned stable_id to GET /api/v2/workspaces/{workspace_id}/contacts as ?stable_id=…, or pass the returned id as ?stored_filter_id=… (requires save: true).

The stable_id token uses the standard gzip+base64 Refine full-state format — the same format the server-rendered filter UI produces and consumes — making tokens fully interoperable between the API and the HTML filter UI.

post/workspaces/{workspace_id}/contacts/filters

Path parameters

workspace_idinteger required

Request body

textstring required

Natural-language description of the audience or filter to generate.

saveboolean

When true, persists the generated filter as a reusable Refine::StoredFilter. The saved filter identity fields are included in the response.

namestring nullable

Human-readable name for the saved filter. Only used when save is true. Must be unique within the workspace when provided.

Example request

{
  "text": "buyers of the $99 course who joined in the last 30 days"
}

Response

Created

idinteger nullable required

Saved filter ID, or null when the filter was not saved (save was falsey).

public_idstring nullable required

Obfuscated saved filter ID, or null when the filter was not saved.

workspace_idinteger nullable required

Workspace ID, or null when the filter was not saved.

namestring nullable required

Name of the saved filter, or null when the filter was not saved or had no name.

stable_idstring required

URL-encoded Refine stable_id token in the standard gzip+base64 full-state format — interoperable with the server-rendered filter UI. Pass as ?stable_id=… to the contacts index (GET /api/v2/workspaces/{workspace_id}/contacts) to apply this filter to the results. Always present in the response.

Example response

{
  "filter": {
    "criteria": [
      {
        "attribute": "tags.id",
        "clause": "in"
      }
    ]
  }
}