POST/v1/contacts/filters/validatebeta

Check a contact filter

Needs: Read your data (mcp:read)
Plan: Any plan with API access
Limits: 300 a minute per key
Undo: Nothing to undo: this only reads.

Checks an advanced contact filter without running a search. Answers valid with every problem (issues, each with its path), the filter as it would run (relative dates turned into absolute ones in your workspace's timezone), warnings, and with count: true how many contacts match.

Use it before saving a filter.

Try it

Edit as JSON

filteroptionalobject (JSON)

38 / 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.

The advanced filter to check (see **Search contacts**).

saved_filter_idoptional

A saved contact filter to include.

countoptionalboolean

`true` = also count the matching contacts.

This only reads. It uses your real data and changes nothing.

curl -X POST 'https://mcp.wa-api.cloud/v1/contacts/filters/validate' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "filter": {
    "createdAt": {
      "gte": "start_of_month"
    }
  },
  "count": true
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
filter	object	The advanced filter to check (see Search contacts).
saved_filter_id	string \| integer	A saved contact filter to include.pattern `^[1-9]\d{0,18}$`
count	boolean	`true` = also count the matching contacts.default `false`

Headers

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}$`

Response `200`

Whether the filter is valid, and how it would run.

Response fields
Field	Type	What it is
validrequired	boolean
issuesrequired	array of object	Why it is not valid (empty when valid).
pathrequired	string
messagerequired	string
reason	string	The refusal class when it has one (filter_too_deep, filter_regex_invalid, saved_filter_not_found, …).
filterrequired	object or null	Your filter, normalised: what `POST /v1/saved-filters` would store.
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
notesrequired	array of string	Normalisations applied.
conditionsrequired	integer	-9007199254740991–9007199254740991
depthrequired	integer	-9007199254740991–9007199254740991
saved_filtersrequired	array of object	Saved filters it uses (applied as part of it).
idrequired	string
namerequired	string
timezonerequired	string or null	Timezone relative dates were resolved in (null when not valid).
countrequired	integer or null	-9007199254740991–9007199254740991
approximaterequired	boolean or null

Errors

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

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field. The request itself is malformed (e.g. `filter` is not an object). A filter that breaks the rules is not an error: the answer is `valid: false` with `issues[]` (each with `path`, `message` and, when it has one, `reason`).
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 (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
502	upstream_error	With `count: true`: the contacts service could not run this filter (`reason: filter_failed`). Simplify it.
503	service_unconfigured	Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.
504	timeout	With `count: true`: counting took too long (`reason: query_timeout`). Narrow the filter.

Examples

Check a filter with a relative date

Request body

{
  "filter": {
    "createdAt": {
      "gte": "start_of_month"
    }
  },
  "count": true
}

Response 200

{
  "valid": true,
  "issues": [],
  "filter": {
    "createdAt": {
      "gte": "2026-08-31T20:00:00.000Z"
    }
  },
  "resolved_dates": [
    {
      "path": "filter.createdAt.gte",
      "input": "start_of_month",
      "value": "2026-08-31T20:00:00.000Z"
    }
  ],
  "warnings": [],
  "notes": [],
  "conditions": 1,
  "depth": 1,
  "saved_filters": [],
  "timezone": "Asia/Dubai",
  "count": 120,
  "approximate": false
}

Operation path

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