Search prospecting contacts by ICP filters

POST https://api.lusha.com/v3/contacts/prospecting takes filter criteria describing your Ideal Customer Profile and returns a paginated list of matching contact previews, each with an id. It does not return full contact records - no emails or phone numbers. To reveal those, pass the id values you want to Enrich Contacts. Before building your request, use the contact filter types and contact filter values endpoints to look up the valid values for each field.

Request body

Send a JSON body with pagination and filters. Filters are split into contacts and companies, each with optional include and exclude sections - include at least one of contacts or companies.

{
  "pagination": { "page": 0, "size": 50 },
  "filters": {
    "contacts": {
      "include": {
        "departments": ["Sales"],
        "seniorityIds": [4, 5],
        "locations": [{ "country": "United States", "state": "California" }]
      }
    },
    "companies": {
      "include": {
        "sizes": [{ "min": 51, "max": 500 }],
        "mainIndustriesIds": [4]
      }
    }
  },
  "options": { "includePartialProfiles": true }
}

Common filter fields

Field	Type	Description
`filters.contacts.include.jobTitles`	string[]	Free-text job titles to match
`filters.contacts.include.seniorityIds`	integer[]	Seniority level IDs - look up valid values via contact filter values
`filters.contacts.include.departments`	string[]	Department names
`filters.contacts.include.locations`	object[]	Objects with `city`, `state`, `country`, `continent`, `countryGrouping`
`filters.contacts.include.existingDataPoints`	string[]	Require specific data types (e.g. `"work_email"`, `"work_phone"`)
`filters.contacts.include.linkedinUrls`	string[]	Match specific LinkedIn profile URLs
`filters.contacts.include.searchText`	string	Free-text search across contact fields (max 200 chars)
`filters.companies.include.mainIndustriesIds` / `subIndustriesIds`	integer[]	Industry IDs
`filters.companies.include.sizes`	object[]	Employee count ranges as `{ "min": ..., "max": ... }`
`options.includePartialProfiles`	boolean	Include contacts with incomplete data. Defaults to `true`.
`options.excludeDnc`	boolean	Exclude contacts whose phones are all Do Not Call - see below
`pagination.page` / `pagination.size`	integer	Pagination - `page` ranges `0–1000`, `size` ranges `10–100`

See the full field reference for every available filter, including company firmographics, funding, and keyword filters.

Signal filtering

Narrow results to contacts at key career moments by filtering on signal types.

Credits are charged for each matched signal type per result, on top of the standard per-result charge.

Add a signals object under filters.contacts.include:

{
  "filters": {
    "contacts": {
      "include": {
        "seniorityIds": [4, 5],
        "departments": ["Engineering & Technical"],
        "signals": {
          "types": ["promotion", "companyChange"],
          "startDate": "2025-01-01"
        }
      }
    }
  },
  "pagination": { "page": 0, "size": 25 }
}

The allowed contact signal values are allSignals, promotion, and companyChange.

DNC filtering

Set "options": { "excludeDnc": true } to filter out contacts whose phone numbers are all marked Do Not Call:

{
  "filters": {
    "contacts": {
      "include": {
        "seniorityIds": [5],
        "departments": ["Sales"]
      }
    }
  },
  "pagination": { "page": 0, "size": 25 },
  "options": { "excludeDnc": true }
}

Example request

curl --request POST \
  --url https://api.lusha.com/v3/contacts/prospecting \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "pagination": { "page": 0, "size": 50 },
    "filters": {
      "contacts": {
        "include": {
          "departments": ["Sales"],
          "locations": [{ "country": "United States" }],
          "existingDataPoints": ["work_email"]
        }
      },
      "companies": {
        "include": {
          "businessModel": ["B2B"],
          "companyType": ["Public Company"]
        }
      }
    },
    "options": { "includePartialProfiles": true }
  }'

{
  "pagination": { "page": 0, "size": 50 },
  "filters": {
    "contacts": {
      "include": {
        "departments": ["Sales"],
        "locations": [{ "country": "United States" }],
        "existingDataPoints": ["work_email"]
      }
    },
    "companies": {
      "include": {
        "businessModel": ["B2B"],
        "companyType": ["Public Company"]
      }
    }
  },
  "options": { "includePartialProfiles": true }
}

Example response

{
  "requestId": "fa828378-7a8e-4e5d-9f72-0270e7f7ab51",
  "pagination": { "page": 0, "size": 50, "total": 670550 },
  "results": [
    {
      "id": "670138733",
      "firstName": "Ting",
      "lastName": "Tsou"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 50
  }
}

Each result’s id is what you pass to Enrich Contacts to reveal full records. Previews may also include has (fields already populated) and canReveal (fields you can reveal, and at what credit cost) - see the full API reference for the complete response schema.

Use the contact filter types and contact filter values endpoints to fetch valid values for seniorityIds, departments, locations, and existingDataPoints before building your search request.

Overview

Resources

Endpoints

Search prospecting contacts by ICP filters

Request body

Common filter fields

Signal filtering

DNC filtering

Example request

Example response

​Request body

​Common filter fields

​Signal filtering

​DNC filtering

​Example request

​Example response

Request body

Common filter fields

Signal filtering

DNC filtering

Example request

Example response