> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cloakup.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign filters

> Allowed values, query params, and filter enums

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

## 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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).

```json theme={null}
"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:

```json theme={null}
"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](/reference/schemas#campaignfilters).