Available contact filters for prospecting searches

Before building a 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.

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

Discover filter types

Call GET /v3/contacts/prospecting/filters. It returns every contact filter type and a requiresQuery flag telling you whether that type needs a search term.

curl --request GET \
  --url https://api.lusha.com/v3/contacts/prospecting/filters \
  --header 'api_key: YOUR_API_KEY'

{
  "availableFilters": [
    { "filterType": "locations", "requiresQuery": true },
    { "filterType": "departments", "requiresQuery": false },
    { "filterType": "seniority", "requiresQuery": false },
    { "filterType": "countries", "requiresQuery": false },
    { "filterType": "existingDataPoints", "requiresQuery": false }
  ]
}

Fetch values for the filter type you need

Call GET /v3/contacts/prospecting/filters/{filterType} with the filterType from step 1. If requiresQuery was true, also pass a query string (2–256 characters).

curl --request GET \
  --url https://api.lusha.com/v3/contacts/prospecting/filters/seniority \
  --header 'api_key: YOUR_API_KEY'

{
  "values": [
    { "id": 4, "name": "Director" },
    { "id": 5, "name": "VP" }
  ]
}

Pass the values into your search request

Nest the selected values under filters.contacts.include in POST /v3/contacts/prospecting:

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

departments, seniority, existingDataPoints, and countries rarely change. Cache their values instead of calling the discovery or values endpoints before every search.

Next steps

Contact Filter Types

Full reference for the discovery endpoint.

Contact Filter Values

Full reference for the values endpoint, including response shapes per filter type.

Overview

Resources

Endpoints

Available contact filters for prospecting searches

The two-step pattern

Which filter types need a query

Next steps

Contact Filter Types

Contact Filter Values

​The two-step pattern

​Which filter types need a query

​Next steps

Contact Filter Types

Contact Filter Values

The two-step pattern

Which filter types need a query

Next steps