Reference

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.

Generated from the contractsView as Markdown

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`
Tag	Catalogue

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

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

{
  "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.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	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.