# Search filter values

> GET /v1/catalogue/filters/{dimension}/values. Values of one field, searched by text, each with its contact and company count, plus did_you_mean for a near miss.

Source: https://emailmovers.com/mydatahub/docs/reference/rest/search-filter-values

`GET /v1/catalogue/filters/{dimension}/values`

Values of one field, searched by text, each with its contact and company count, plus did_you_mean for a near miss. The dimension is the field name, such as site.town.

| Property | Value |
| --- | --- |
| Endpoint | `GET https://mydatahub.emailmovers.com/v1/catalogue/filters/{dimension}/values` |
| Operation id | `searchFilterValues` |
| Cost | Free (0 credits) |
| Access | No account, key or token needed. |
| MCP tool | [`search_filter_values`](https://emailmovers.com/mydatahub/docs/reference/mcp/search_filter_values.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 |
| --- | --- | --- | --- | --- |
| `dimension` | path | string | yes | A field name from GET /v1/catalogue/filters, such as site.town. |
| `q` | query | string | no | Text to search for. |
| `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. |
| `limit` | query | integer (1 to 100) | no | Items per page, 1 to 100. Default 25. |
| `cursor` | query | string | no | An opaque cursor from next_cursor. Pass it back unchanged. |
| `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/site.town/values"
```

## Responses

### 200: A page of values.

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

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `field` | string | yes |  |
| `dataset_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `data` | array of `FilterValue` | yes |  |
| `data[].code` | string or number or boolean | yes | The value to use in a filter. |
| `data[].label` | string | yes |  |
| `data[].contacts` | integer (0 or more) or `under 10` or `suppressed` | yes | A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5. |
| `data[].companies` | integer (0 or more) or `under 10` or `suppressed` | yes | A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5. |
| `data[].parent` | string or null | no | The parent code for hierarchical fields, such as SIC division 62 under J. |
| `has_more` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |
| `did_you_mean` | array of string | no |  |
| `disclosure` | `Disclosure` | yes | Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers. |
| `disclosure.level` | enum: `exact`, `rounded` | yes | exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5. |
| `disclosure.rounded_to` | integer or null | yes | 5 when numbers are rounded; null when they are exact. |
| `disclosure.secondary_suppression` | boolean | yes | True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced. |
| `disclosure.notes` | array of string | yes |  |

#### Example response

```json
{
  "field": "site.town",
  "dataset_version": "2026-W39",
  "data": [
    {
      "code": "leeds",
      "label": "Leeds",
      "contacts": 41210,
      "companies": 9870,
      "parent": "west_yorkshire"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "disclosure": {
    "level": "rounded",
    "rounded_to": 5,
    "secondary_suppression": false,
    "notes": [
      "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers."
    ]
  }
}
```

## 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. |
| 404 | [`not-found`](https://emailmovers.com/mydatahub/docs/errors/not-found.md) | No such object for this organisation. |
| 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. |