Contact Filter Values

GET

contacts

prospecting

filters

{filterType}

Get Contact Filter Values

curl --request GET \
  --url https://api.lusha.com/v3/contacts/prospecting/filters/{filterType} \
  --header 'api_key: <api-key>'

const options = {method: 'GET', headers: {api_key: '<api-key>'}};

fetch('https://api.lusha.com/v3/contacts/prospecting/filters/{filterType}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lusha.com/v3/contacts/prospecting/filters/{filterType}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("api_key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "values": "<unknown>"
}

Returns the valid values for one contact filter type. Call Contact Filter Types first if you don’t already know which filterType values are available.

Filter type	Query required?	Maps to (in Prospecting Contacts)
`departments`	No	`filters.contacts.include.departments`
`seniority`	No	`filters.contacts.include.seniorityIds`
`existingDataPoints`	No	`filters.contacts.include.existingDataPoints`
`countries`	No	`filters.contacts.include.countries`
`locations`	Yes (2–256 chars)	`filters.contacts.include.locations`

Endpoint

GET https://api.lusha.com/v3/contacts/prospecting/filters/{filterType}

Authentication

string

required

Your Lusha API key.

Path parameters

string

required

The filter type to fetch values for.Allowed values: departments, seniority, existingDataPoints, countries, locations

Query parameters

string

Search term to filter the returned values. Required for locations (2–256 characters); optional and ignored for filter types that don’t require a query.

Response

any

The valid values for the requested filterType. The shape depends on which filter type you requested:

departments - an array of department name strings, for example ["Sales", "Engineering"]
existingDataPoints - an array of data point strings, for example ["work_email", "work_phone"]
countries - an array of country code strings, for example ["US", "CA"]
seniority - an array of { id, name } objects; pass the id values in seniorityIds
locations - an array of location objects with city, state, country, continent, and countryGrouping, matching the shape used in search requests

The OpenAPI schema declares values as an open-ended field since its shape varies by filter type. Treat the examples above as representative, not a fixed contract.

Error codes

Status	Meaning
`400`	Bad request - invalid `filterType`, or missing/too-short `query` for a filter type that requires one
`401`	Unauthorized - invalid or missing API key
`403`	Forbidden - account inactive or V3 access not enabled
`429`	Too many requests - rate limit exceeded

Examples

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

curl --request GET \
  --url 'https://api.lusha.com/v3/contacts/prospecting/filters/locations?query=San%20Francisco' \
  --header 'api_key: YOUR_API_KEY'

Example response - seniority

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

Example response - locations

{
  "values": [
    {
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "continent": "North America",
      "countryGrouping": "AMER"
    }
  ]
}

Filter types with requiresQuery: false (departments, seniority, existingDataPoints, countries) rarely change - cache their values instead of calling this endpoint before every search.

Authorizations

api_key

string

header

required

Your Lusha API key. You can find this in your Lusha dashboard under API settings. Include this key in the api_key header for all requests.

Path Parameters

filterType

enum<string>

required

Available options:

departments,

seniority,

existingDataPoints,

countries,

locations

Query Parameters

query

string

Required string length: 2 - 256

Response

Successful response

values

any | null

Filter values (shape depends on filter type)

⌘I

Get Contact Filter Values

curl --request GET \
  --url https://api.lusha.com/v3/contacts/prospecting/filters/{filterType} \
  --header 'api_key: <api-key>'

const options = {method: 'GET', headers: {api_key: '<api-key>'}};

fetch('https://api.lusha.com/v3/contacts/prospecting/filters/{filterType}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lusha.com/v3/contacts/prospecting/filters/{filterType}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("api_key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "values": "<unknown>"
}

Overview

Resources

Endpoints

Endpoint

Authentication

Path parameters

Query parameters

Response

Error codes

Examples

Authorizations

Path Parameters

Query Parameters

Response

​Endpoint

​Authentication

​Path parameters

​Query parameters

​Response

​Error codes

​Examples

Authorizations

Path Parameters

Query Parameters

Response

Endpoint

Authentication

Path parameters

Query parameters

Response

Error codes

Examples