# List filter fields

> GET /v1/catalogue/filters. Every filterable field of mydatahub.audience/1 with its group, type, operators, value count and default, plus the operators and the dataset list.

Source: https://emailmovers.com/mydatahub/docs/reference/rest/list-filters

`GET /v1/catalogue/filters`

Every filterable field of mydatahub.audience/1 with its group, type, operators, value count and default, plus the operators and the dataset list. Free and public, cached for 24 hours.

| Property | Value |
| --- | --- |
| Endpoint | `GET https://mydatahub.emailmovers.com/v1/catalogue/filters` |
| Operation id | `listFilters` |
| Cost | Free (0 credits) |
| Access | No account, key or token needed. |
| MCP tool | [`list_filters`](https://emailmovers.com/mydatahub/docs/reference/mcp/list_filters.md) |
| Tag | Catalogue |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This page describes the contract the API is tested against.

## Request

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dataset` | query | enum: `uk_contacts`, `ie_contacts`, `global_contacts` | no | The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served. |
| `MyDataHub-Version` | header | string | no | The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window. |

## Example request

```bash
curl "https://mydatahub.emailmovers.com/v1/catalogue/filters"
```

## Responses

### 200: The filter catalogue.

Headers: `RateLimit`, `RateLimit-Policy`.

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `dataset` | enum: `uk_contacts`, `ie_contacts`, `global_contacts` | yes | The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served. |
| `dataset_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `fields` | array of `FilterDimension` | yes |  |
| `fields[].field` | string | yes | The field name, also the dimension slug. |
| `fields[].group` | enum: `company`, `site`, `contact`, `email`, `phone`, `signal` | yes |  |
| `fields[].type` | enum: `enum`, `text`, `number`, `date`, `geo`, `hashed_list`, `boolean`, `band` | yes |  |
| `fields[].label` | string | yes |  |
| `fields[].description` | string | yes |  |
| `fields[].operators` | array of enum: `in`, `between`, `gte`, `lte`, `matches`, `within_radius`, `in_list`, `since` | yes |  |
| `fields[].facet` | boolean | yes | Usable in breakdown_by. |
| `fields[].value_count` | integer (0 or more) or null | yes | Distinct values in this dataset version; null for free text and numbers. |
| `fields[].default` | string or null | yes |  |
| `fields[].examples` | array of string or number or boolean | yes |  |
| `fields[].values_url` | string or null | yes | Where to search the values, or null when the field has none to list. |
| `operators` | array of `OperatorInfo` | yes |  |
| `operators[].op` | enum: `in`, `between`, `gte`, `lte`, `matches`, `within_radius`, `in_list`, `since`, and 3 more | yes |  |
| `operators[].applies_to` | string | yes |  |
| `operators[].description` | string | yes |  |
| `datasets` | array of `Dataset` | yes |  |
| `datasets[].id` | enum: `uk_contacts`, `ie_contacts`, `global_contacts` | yes | The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served. |
| `datasets[].name` | string | yes |  |
| `datasets[].status` | enum: `live`, `planned`, `through_our_team` | yes | live is served; planned is not yet served; through_our_team is sold through the bespoke service only. |
| `datasets[].owner` | string | yes |  |
| `datasets[].source` | string | yes |  |
| `datasets[].licence` | string | yes |  |
| `datasets[].refresh` | string | yes |  |
| `datasets[].residency` | string | yes |  |
| `datasets[].regulator` | string | yes |  |
| `datasets[].warranty` | string | yes |  |
| `datasets[].credits_per_record` | number (0 or more) | yes | 1 for owned UK and Irish data. |
| `datasets[].credits_status` | enum: `confirmed`, `proposed` | yes |  |
| `datasets[].current_version` | string or null | yes |  |
| `datasets[].versions_available` | integer (0 or more) | yes | Immutable weekly versions still queryable (the last 52). |

#### Example response

```json
{
  "dataset": "uk_contacts",
  "dataset_version": "2026-W39",
  "fields": [
    {
      "field": "company.employee_band",
      "group": "company",
      "type": "band",
      "label": "Employee band",
      "description": "Company size in 13 bands, 1-5 to 10000+.",
      "operators": ["in", "between", "gte", "lte"],
      "facet": true,
      "value_count": 14,
      "default": null,
      "examples": ["50-99"],
      "values_url": "/v1/catalogue/filters/company.employee_band/values"
    }
  ],
  "operators": [
    {
      "op": "gte",
      "applies_to": "banded and ranked fields",
      "description": "The value and everything after it in the order (for bands, larger bands)."
    }
  ],
  "datasets": [
    {
      "id": "uk_contacts",
      "name": "UK contacts",
      "status": "live",
      "owner": "Emailmovers Ltd",
      "source": "Emailmovers research; Companies House (OGL v3.0); ONSPD (OGL v3.0)",
      "licence": "12 month multi-use licence; resale prohibited",
      "refresh": "Immutable weekly build every Monday; same-day suppression overlay",
      "residency": "Held in the UK (Google Cloud London)",
      "regulator": "ICO",
      "warranty": "Replacement when hard bounces exceed 10 percent of an order",
      "credits_per_record": 1,
      "credits_status": "confirmed",
      "current_version": "2026-W39",
      "versions_available": 52
    }
  ]
}
```

## Errors

Every error is a problem object with a `code` and a `next_step`. Every response carries the `RateLimit` and `RateLimit-Policy` headers; see [Rate limits](https://emailmovers.com/mydatahub/docs/rate-limits.md).

| Status | Problem codes | When |
| --- | --- | --- |
| 400 | [`invalid-request`](https://emailmovers.com/mydatahub/docs/errors/invalid-request.md), [`idempotency-key-required`](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-required.md), [`unsupported-version`](https://emailmovers.com/mydatahub/docs/errors/unsupported-version.md) | The request could not be read, or an Idempotency-Key is missing. |
| 422 | [`validation-failed`](https://emailmovers.com/mydatahub/docs/errors/validation-failed.md), [`quote-required`](https://emailmovers.com/mydatahub/docs/errors/quote-required.md), [`dataset-unavailable`](https://emailmovers.com/mydatahub/docs/errors/dataset-unavailable.md) | The request is not valid. errors lists every problem with a JSON pointer and did_you_mean. |
| 429 | [`rate-limited`](https://emailmovers.com/mydatahub/docs/errors/rate-limited.md) | Too many requests. Wait for Retry-After. |
| Any other failure | [`internal-error`](https://emailmovers.com/mydatahub/docs/errors/internal-error.md), [`service-unavailable`](https://emailmovers.com/mydatahub/docs/errors/service-unavailable.md), [`tps-screen-expired`](https://emailmovers.com/mydatahub/docs/errors/tps-screen-expired.md) | Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old. |