Skip to content
API PlatformDevelopers
PATCH/v1/saved-filters/{saved_filter_id}beta

Change a saved filter

Needs
Create and edit contacts, tags, contact groups and custom fields (crm:write)
Plan
Any plan with API access
Limits
60 a minute per key
Dry run
Yes — a full preview with ?dry_run=true
Undo
Change it back with the old values (read them first with Get a saved filter).

Renames a saved contact filter, changes its description, or replaces its filter. Only the staff member who saved it can change it. Fields you leave out stay as they are. changes lists the fields whose saved value differs.

Try it with ?dry_run=true first: every check the change runs (ownership included), and the answer is the saved filter as it would be after it, with changes; nothing is saved. Add count=true to also count the contacts it would match; if counting fails, the preview still answers (count: null and count_error).

Try it

Path

The saved filter id.

Query (1)

With `dry_run=true`: also count the contacts it would match.

Body

New name.

New description; `null` clears it.

0 / 16,384 bytes as JSON

Limits: at most 8 levels deep, 60 conditions, 500 items per list, 500 characters per value, regex ≤ 200 characters, 16 KB in all. Format, operators and recipes: Filtering contacts.

New filter (replaces the old one).

Test mode (dry run): nothing will change
Turns test mode off for this page only. It switches back when you leave the page.

Code and response

curl -X PATCH 'https://mcp.wa-api.cloud/v1/saved-filters/7?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Dubai VIPs (2026)"
}'

The code reads your key from $API_KEY.

Parameters

Parameters
FieldTypeWhat it is
saved_filter_idrequiredstring | integer · pathThe saved filter id.pattern ^[1-9]\d{0,18}$
countboolean · queryWith dry_run=true: also count the contacts it would match.

Body

Body fields
FieldTypeWhat it is
namestringNew name.1–255 characters
descriptionstring or nullNew description; null clears it.0–1000 characters
filterobjectNew filter (replaces the old one).

Headers

Headers
FieldTypeWhat it is
AuthorizationrequiredheaderBearer $API_KEY — your API key.
Api-VersionheaderThe API version to use, e.g. 2026-10-01. Default: the version your key is pinned to.one of: 2026-10-01 · pattern ^\d{4}-\d{2}-\d{2}$

Response 200

The saved filter as it is now (with `dry_run=true`: as it would be).

Response fields
FieldTypeWhat it is
saved_filterrequiredobject
idrequiredstring
namerequiredstring
descriptionrequiredstring or null
owner_staff_idrequiredstring or null
filterrequiredobjectThe definition as stored: the panel format, dates absolute.
updated_atrequiredstring or nullnull in a dry run.
changesrequiredarray of stringFields whose saved value differs after this change (empty: it changes nothing).
resolved_datesrequiredarray of object
pathrequiredstring
inputrequiredstring
valuerequiredstring
warningsrequiredarray of objectFilter conditions that may not mean what they look like: {path, message}.
pathstring
messagerequiredstring
dry_runbooleantrue when this was a dry run: every check ran and nothing changed.
countinteger or nullWith dryRun + count: contacts it would match now (null when the count failed: see countError).-9007199254740991–9007199254740991
approximateboolean or nullWith count: the service counted approximately.
count_errorobjectWhy the count is missing. The preview itself is still valid.
coderequiredstring
messagerequiredstring

Errors

Errors are application/problem+json. Branch on code.

StatusCodeWhen
400invalid_input

A field is missing or has the wrong format. errors[] points at each field. The new filter is not valid (as for Save a contact filter; a filter may not contain itself: reason: saved_filter_cycle), it is larger than 32 KB, what the change keeps from the stored filter breaks the platform's limits (a filter or panel settings over 32 KB saved before the limit existed), the saved filter is a conversation filter, or count=true without dry_run=true.

401unauthenticated

The Authorization header is missing, the key is unknown, expired or revoked.

403entitlement_required

The workspace's plan does not include API access (api_access).

403forbidden

Someone else saved it (reason: not_owner, with owner_staff_id), or the new filter compares phone numbers, which are hidden from this staff member (reason: phone_hidden).

403insufficient_scope

The key does not have the permission this operation needs.

404not_found

No saved filter with this id in your workspace, or the new filter names one that does not exist (reason: saved_filter_not_found).

429rate_limited

The key or workspace went over its rate limit. Wait for Retry-After seconds.

503upstream_unavailable

A service behind the API is briefly unavailable. Safe to retry with backoff.

504timeout

The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

Rename a saved filter

Request body

{
  "name": "Dubai VIPs (2026)"
}

Response 200

{
  "saved_filter": {
    "id": "7",
    "name": "Dubai VIPs (2026)",
    "description": null,
    "owner_staff_id": "501",
    "filter": {
      "attributes": {
        "some": {
          "attributeName": {
            "eq": "city"
          },
          "stringValue": {
            "eq": "Dubai"
          }
        }
      }
    },
    "updated_at": "2026-09-30T08:05:00.000Z"
  },
  "changes": [
    "name"
  ],
  "resolved_dates": [],
  "warnings": []
}
Preview a new filter (dry run)

Request body

{
  "filter": {
    "createdAt": {
      "gte": "-30d"
    }
  }
}

Response 200

{
  "saved_filter": {
    "id": "7",
    "name": "Dubai VIPs",
    "description": null,
    "owner_staff_id": "501",
    "filter": {
      "createdAt": {
        "gte": "2026-08-31T08:00:00.000Z"
      }
    },
    "updated_at": null
  },
  "changes": [
    "filter"
  ],
  "resolved_dates": [
    {
      "path": "filter.createdAt.gte",
      "input": "-30d",
      "value": "2026-08-31T08:00:00.000Z"
    }
  ],
  "warnings": [],
  "dry_run": true
}

Operation path

The same operation is also at POST /v1/ops/crm_update_saved_filter, with every field in the JSON body.