/v1/saved-filtersbetaSave a contact 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
- Delete it with Delete a saved filter.
Saves an advanced contact filter under a name. Your whole team sees it, it opens in the app's contacts page, and Search contacts can apply it by id.
It is checked first, like Check a contact filter. Relative dates are saved as the absolute dates they mean now.
Try it with ?dry_run=true first: every check the save runs, and the answer is the saved filter exactly as it would be stored (your name, your filter with its dates made absolute, id: null); nothing is saved and no Idempotency-Key is needed. 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
Query (1)
With `dry_run=true`: also count the contacts it would match.
Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.
Code and response
curl -X POST 'https://mcp.wa-api.cloud/v1/saved-filters?dry_run=true' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Dubai VIPs",
"filter": {
"attributes": {
"some": {
"attributeName": {
"eq": "city"
},
"stringValue": {
"eq": "Dubai"
}
}
}
}
}'The code reads your key from $API_KEY.
Parameters
| Field | Type | What it is |
|---|---|---|
| count | boolean · query | With dry_run=true: also count the contacts it would match. |
Body
| Field | Type | What it is |
|---|---|---|
| namerequired | string | Name shown in the app (1–255 characters).1–255 characters |
| description | string | Optional description (up to 1000 characters).0–1000 characters |
| filterrequired | object | The filter to save (the Search contacts format). |
Headers
| Field | Type | What it is |
|---|---|---|
| Authorizationrequired | header | Bearer $API_KEY — your API key. |
| Api-Version | header | The 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}$ |
| Idempotency-Key | header | Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.pattern ^[A-Za-z0-9._:-]+$ · 8–128 characters |
Response 201
The saved filter (with `dry_run=true`: as it would be saved, `id: null`).
| Field | Type | What it is |
|---|---|---|
| saved_filterrequired | object | |
| idrequired | string or null | null in a dry run: known only when it is saved. |
| namerequired | string | |
| descriptionrequired | string or null | |
| owner_staff_idrequired | string or null | |
| filterrequired | object | The definition as stored: the panel format, dates absolute. |
| updated_atrequired | string or null | null in a dry run. |
| resolved_datesrequired | array of object | |
| pathrequired | string | |
| inputrequired | string | |
| valuerequired | string | |
| warningsrequired | array of object | Filter conditions that may not mean what they look like: {path, message}. |
| path | string | |
| messagerequired | string | |
| dry_run | boolean | true when this was a dry run: every check ran and nothing changed. |
| count | integer or null | With dryRun + count: contacts it would match now (null when the count failed: see countError).-9007199254740991–9007199254740991 |
| approximate | boolean or null | With count: the service counted approximately. |
| count_error | object | Why the count is missing. The preview itself is still valid. |
| coderequired | string | |
| messagerequired | string |
Errors
Errors are application/problem+json. Branch on code.
| Status | Code | When |
|---|---|---|
| 400 | invalid_input | A field is missing or has the wrong format. |
| 401 | unauthenticated | The Authorization header is missing, the key is unknown, expired or revoked. |
| 403 | entitlement_required | The workspace's plan does not include API access ( |
| 403 | forbidden | The filter compares phone numbers, which are hidden from this staff member ( |
| 403 | insufficient_scope | The key does not have the permission this operation needs. |
| 404 | not_found | A saved filter it names does not exist in your workspace ( |
| 409 | conflict | Also returned while a request with the same Idempotency-Key is still running. |
| 429 | rate_limited | The key or workspace went over its rate limit. Wait for |
| 503 | upstream_unavailable | A service behind the API is briefly unavailable. Safe to retry with backoff. |
| 504 | timeout | The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice. |
Examples
Save "Dubai VIPs"
Request body
{
"name": "Dubai VIPs",
"filter": {
"attributes": {
"some": {
"attributeName": {
"eq": "city"
},
"stringValue": {
"eq": "Dubai"
}
}
}
}
}Response 201
{
"saved_filter": {
"id": "7",
"name": "Dubai VIPs",
"description": null,
"owner_staff_id": "501",
"filter": {
"attributes": {
"some": {
"attributeName": {
"eq": "city"
},
"stringValue": {
"eq": "Dubai"
}
}
}
},
"updated_at": "2026-09-30T08:00:00.000Z"
},
"resolved_dates": [],
"warnings": []
}Preview a save and count its matches (dry run)
Request body
{
"name": "New this month",
"filter": {
"createdAt": {
"gte": "start_of_month"
}
}
}Response 201
{
"saved_filter": {
"id": null,
"name": "New this month",
"description": null,
"owner_staff_id": "501",
"filter": {
"createdAt": {
"gte": "2026-08-31T20:00:00.000Z"
}
},
"updated_at": null
},
"resolved_dates": [
{
"path": "filter.createdAt.gte",
"input": "start_of_month",
"value": "2026-08-31T20:00:00.000Z"
}
],
"warnings": [],
"dry_run": true,
"count": 120,
"approximate": false
}Operation path
The same operation is also at POST /v1/ops/crm_create_saved_filter, with every field in the JSON body.