Campaign filters

Create/update returns 422 if a value does not match the format or is not in the API allowlist. Do not guess country names or free-form locale strings.

Allowed values

Field	Type	Max items	Format
`filters.geolocation.countries`	`string[]`	256	ISO 3166-1 alpha-2, uppercase
`filters.browser_language.languages`	`string[]`	255	IETF language tag, all lowercase (`xx` or `xx-yy`)
`filters.state.states`	`string[]`	100	Place name (see below)
`filters.city.cities`	`string[]`	100	Place name (see below)
`pages.offers[].segmentation.country`	`string[]`	256	Same as `filters.geolocation.countries`

Country codes

Used in filters.geolocation.countries and pages.offers[].segmentation.country.

Rule	Value
Format	Exactly 2 uppercase letters (ISO 3166-1 alpha-2)
Examples	`"BR"`, `"US"`, `"PT"`
Invalid	`"br"`, `"Brazil"`, `"BRA"`, `"brasil"`

Browser language codes

Used in filters.browser_language.languages.

Rule	Value
Format	Lowercase IETF language tag: `xx` or `xx-yy` (hyphen, not underscore)
Examples	`"pt-br"`, `"en"`, `"es"`
Invalid	`"pt-BR"`, `"portuguese"`, `"pt_BR"`

State and city names

Used in filters.state.states and filters.city.cities.

Rule	Value
Length	1–100 characters (trimmed)
Allowed chars	Unicode letters, spaces, `'`, `-`, `.`
Must start with	A letter
Examples	`"São Paulo"`, `"California"`, `"St. Louis"`
Invalid	`"123"`, `""`, `"City@Name"`

Free-text GeoIP place names — not ISO codes.

URL query params (`filters.query`)

Cloakup matches URL query parameters against filters.query.params. Each key maps to an array of allowed values (not a plain string).

"query": {
  "allow": true,
  "remove_params": false,
  "condition": "some",
  "params": {
    "utm_source": ["google"]
  },
  "rules": {
    "utm_source": "equals"
  }
}

Field	Type	Description
`params`	`Record<string, string[]>`	Param name → list of allowed values in the URL
`rules`	`Record<string, string>`	Per-param rule: `equals`, `contains`, `starts_with`, `ends_with`
`condition`	`"some"` \| `"every"`	`some` = at least one param must match; `every` = all must match
`allow`	`boolean`	`true` = allow when params match; `false` = block when params match
`remove_params`	`boolean`	Strip matched params from URL before redirect

Wildcard

Use "*" as the value to accept any value for that param key:

"params": {
  "utm_source": ["*"]
},
"rules": {
  "utm_source": "equals"
}

This only checks that utm_source exists in the URL — the actual value does not matter. Empty params: {} means no URL param filtering.

Required filter keys

On create/update, these top-level keys under filters must be present: geolocation, referer, query, domain, browser, browser_language, isp, os, user_agent, blacklist Optional keys (defaults apply): ad-network flags, deny_always, bots, proxy, adspy, cloakup_ai, state, city, network_type, device, whitelist. Full JSON Schema: Schemas → CampaignFilters.

Getting started

Guides

API reference

Reference

Allowed values

Country codes

Browser language codes

State and city names

URL query params (`filters.query`)

Wildcard

Required filter keys

​Allowed values

​Country codes

​Browser language codes

​State and city names

​URL query params (filters.query)

​Wildcard

​Required filter keys

Allowed values

Country codes

Browser language codes

State and city names

URL query params (`filters.query`)

Wildcard

Required filter keys