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

# Available contact filters for prospecting searches

> Discover contact filter types and retrieve their valid values with two generic endpoints, then use them in a Prospecting Contacts search.

Before building a [Prospecting Contacts](https://docs.lusha.com/api-reference/prospecting/prospecting-contacts.md) request, use the Filters API to retrieve the exact values Lusha accepts. Passing unrecognized values causes searches to return no results, so fetching valid options first is the recommended approach.

> [!NOTE]
>
> **V3 change:** contact filters are no longer one endpoint per filter type. V3 collapses discovery and lookup into two generic endpoints - the same two endpoints work for every filter type; the `filterType` you pass tells the API which dimension you want.

## The two-step pattern

**1. Discover filter types**

Call [`GET /v3/contacts/prospecting/filters`](https://docs.lusha.com/api-reference/filters/contact-filter-types). It returns every contact filter type and a `requiresQuery` flag telling you whether that type needs a search term.

```bash theme={null}
curl --request GET \
  --url https://api.lusha.com/v3/contacts/prospecting/filters \
  --header 'api_key: YOUR_API_KEY'
```

```json theme={null}
{
  "availableFilters": [
    { "filterType": "locations", "requiresQuery": true },
    { "filterType": "departments", "requiresQuery": false },
    { "filterType": "seniority", "requiresQuery": false },
    { "filterType": "countries", "requiresQuery": false },
    { "filterType": "existingDataPoints", "requiresQuery": false }
  ]
}
```

**2. Fetch values for the filter type you need**

Call [`GET /v3/contacts/prospecting/filters/{filterType}`](https://docs.lusha.com/api-reference/filters/contact-filter-values) with the `filterType` from step 1. If `requiresQuery` was `true`, also pass a `query` string (2–256 characters).

```bash theme={null}
curl --request GET \
  --url https://api.lusha.com/v3/contacts/prospecting/filters/seniority \
  --header 'api_key: YOUR_API_KEY'
```

```json theme={null}
{
  "values": [
    { "id": 4, "name": "Director" },
    { "id": 5, "name": "VP" }
  ]
}
```

**3. Pass the values into your search request**

Nest the selected values under `filters.contacts.include` in [`POST /v3/contacts/prospecting`](https://docs.lusha.com/api-reference/prospecting/prospecting-contacts):

```json theme={null}
{
  "filters": {
    "contacts": {
      "include": {
        "departments": ["Engineering"],
        "seniorityIds": [4, 5]
      }
    }
  }
}
```

## Which filter types need a query

| Filter type | Query required? | Search request field |
| - | - | - |
| `departments` | No - returns the full list | `filters.contacts.include.departments` |
| `seniority` | No - returns the full list | `filters.contacts.include.seniorityIds` |
| `existingDataPoints` | No - returns the full list | `filters.contacts.include.existingDataPoints` |
| `countries` | No - returns the full list | `filters.contacts.include.countries` |
| `locations` | **Yes** - pass `query` (2–256 chars) | `filters.contacts.include.locations` |

`departments`, `seniority`, `existingDataPoints`, and `countries` return their entire value set in one call - there's nothing to search for. `locations` is the exception: because the location taxonomy is too large to return in full, you search it with a free-text `query` (for example, `"San Francisco"`) and get back matching location objects.

> [!TIP]
>
> `departments`, `seniority`, `existingDataPoints`, and `countries` rarely change. Cache their values instead of calling the discovery or values endpoints before every search.

## Next steps

> [card] [Contact Filter Types](https://docs.lusha.com/api-reference/filters/contact-filter-types)
>
> Full reference for the discovery endpoint.

> [card] [Contact Filter Values](https://docs.lusha.com/api-reference/filters/contact-filter-values)
>
> Full reference for the values endpoint, including response shapes per filter type.


## Related topics

- [Search prospecting contacts by ICP filters](https://docs.lusha.com/prospecting/search-contacts.md)
- [Available company filters for prospecting searches](https://docs.lusha.com/filters/company-filters.md)
- [Account-Based Prospecting (Beta)](https://docs.lusha.com/user-guide/getting-started-with-prospecting/account-based-prospecting-beta.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.