> ## 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](/api-reference/prospecting/prospecting-contacts) 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.

<Info>
  **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.
</Info>

## The two-step pattern

<Steps>
  <Step title="Discover filter types">
    Call [`GET /v3/contacts/prospecting/filters`](/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 }
      ]
    }
    ```
  </Step>

  <Step title="Fetch values for the filter type you need">
    Call [`GET /v3/contacts/prospecting/filters/{filterType}`](/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" }
      ]
    }
    ```
  </Step>

  <Step title="Pass the values into your search request">
    Nest the selected values under `filters.contacts.include` in [`POST /v3/contacts/prospecting`](/api-reference/prospecting/prospecting-contacts):

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

## 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.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Contact Filter Types" icon="list" href="/api-reference/filters/contact-filter-types">
    Full reference for the discovery endpoint.
  </Card>

  <Card title="Contact Filter Values" icon="magnifying-glass" href="/api-reference/filters/contact-filter-values">
    Full reference for the values endpoint, including response shapes per filter type.
  </Card>
</CardGroup>