> ## 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

> Retrieve valid filter values for departments, seniority, data points, countries, and locations to use in contact prospecting searches.

Before building a contact search request, use these filter endpoints to retrieve the exact values the API accepts. Passing unrecognized values causes searches to return no results, so fetching valid options first is the recommended approach.

All filter values returned here are intended for use in `POST /prospecting/contact/search`.

## Available filter endpoints

| Filter      | Endpoint                                             | Method             |
| ----------- | ---------------------------------------------------- | ------------------ |
| Departments | `/prospecting/filters/contacts/departments`          | GET                |
| Seniority   | `/prospecting/filters/contacts/seniority`            | GET                |
| Data points | `/prospecting/filters/contacts/existing_data_points` | GET                |
| Countries   | `/prospecting/filters/contacts/all_countries`        | GET                |
| Locations   | `/prospecting/filters/contacts/locations`            | POST (text search) |

## How to use these endpoints

The typical workflow is to call a filter endpoint, pick the values you want, and pass them directly into your search request body.

<Steps>
  <Step title="Fetch valid filter values">
    Call the filter endpoint for the dimension you want to filter on. For example, to get the list of departments:

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

    The response is a bare array of valid department values:

    ```json theme={null}
    ["Engineering", "Sales", "Marketing", "Finance", "Operations"]
    ```
  </Step>

  <Step title="Pick the values you need">
    Select the values that match your ideal customer profile. For example: `"Engineering"`.
  </Step>

  <Step title="Pass them into your search request">
    Nest the selected values under `filters.contacts.include` in `POST /prospecting/contact/search`:

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

    Seniority is filtered by the numeric `id` values returned by the seniority filter endpoint, not by name strings.
  </Step>
</Steps>

## Location search

The locations endpoint accepts a text query in the `text` field and returns matching location objects you can use in your search. This is useful when you want to target a specific city or region and need the exact values the API recognizes.

```bash theme={null}
curl --request POST \
  --url https://api.lusha.com/prospecting/filters/contacts/locations \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "New York" }'
```

```json theme={null}
[
  {
    "continent": "North America",
    "country": "United States",
    "city": "New York",
    "state": "New York",
    "country_grouping": "na"
  }
]
```

## Endpoint details

### GET /prospecting/filters/contacts/departments

Returns the list of departments available for filtering contacts.

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

### GET /prospecting/filters/contacts/seniority

Returns all seniority levels as `{id, name}` objects (e.g., founder, c-suite, vice president). Filter by the numeric `id` values.

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

### GET /prospecting/filters/contacts/existing\_data\_points

Returns available data point types you can require to be present on returned contacts (e.g., work\_email, phone, direct\_phone).

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

### GET /prospecting/filters/contacts/all\_countries

Returns the full list of countries available for contact location filtering. There is no standalone `countries` filter field - use the `country` values returned here inside a `locations` entry (see [Location search](#location-search)).

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

### POST /prospecting/filters/contacts/locations

Searches for location objects by free-text query. Use the returned objects (or the fields you need from them) in your search request.

```bash theme={null}
curl --request POST \
  --url https://api.lusha.com/prospecting/filters/contacts/locations \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "San Francisco" }'
```

<Tip>
  Cache responses from the GET filter endpoints. Department, seniority, country, and data point values rarely change and do not need to be fetched on every search run.
</Tip>