Search prospecting contacts by ICP filters

POST https://api.lusha.com/prospecting/contact/search is step 2 of the 3-step prospecting flow. You pass a set of filters that describe your Ideal Customer Profile and receive back a paginated list of matching contacts, each with a contactId. No credits are consumed at this step - credits are charged when you enrich the results in step 3. Before building your request, use the Contact Filters endpoints to look up the valid values for each field.

Request body

Send a JSON body with a filters object. Filters are split into contacts and companies, each with include and exclude sections. All filter fields are optional - include only the ones relevant to your ICP.

{
  "filters": {
    "contacts": {
      "include": {
        "jobTitles": ["VP of Sales", "Head of Sales"],
        "seniority": [4, 5],
        "departments": ["Sales"],
        "locations": [
          { "country": "United States", "state": "California" }
        ]
      }
    },
    "companies": {
      "include": {
        "sizes": [{ "min": 51, "max": 500 }],
        "mainIndustriesIds": [4]
      }
    }
  },
  "pages": { "page": 0, "size": 25 }
}

Common filter fields

Field	Type	Description
`filters.contacts.include.jobTitles`	string[]	Free-text job titles to match
`filters.contacts.include.seniority`	number[]	Seniority level IDs - use GET /prospecting/filters/contacts/seniority for valid values
`filters.contacts.include.departments`	string[]	Department names - use GET /prospecting/filters/contacts/departments
`filters.contacts.include.locations`	object[]	Objects with `continent`, `country`, `state`, `city`, and `country_grouping`
`filters.contacts.include.existing_data_points`	string[]	Require specific data types (e.g. `"phone"`, `"work_email"`, `"mobile_phone"`) - use GET /prospecting/filters/contacts/existing_data_points
`filters.contacts.include.linkedinUrls`	string[]	Match specific LinkedIn profile URLs
`filters.contacts.include.searchText`	string	Free-text search across contact fields
`filters.companies.include.mainIndustriesIds` / `subIndustriesIds`	number[]	Industry IDs - use GET /prospecting/filters/companies/industries_labels
`filters.companies.include.sizes`	object[]	Employee count ranges as `{ "min": ..., "max": ... }`
`includePartialContact`	boolean	Include contacts with incomplete data. Defaults to `true`.
`excludeDnc`	boolean	Scale-plan feature - see DNC filtering below
`pages.page` / `pages.size`	number	Pagination - `page` ranges `0–1000`, `size` ranges `10–50`

Signal filtering (premium feature)

You can narrow results to contacts at key career moments by filtering on signal types.

Signal filtering is a premium feature. Credits are charged for each signal type that returns results.

Add a signal object under filters.contacts.include to match contacts who have recently experienced a specific event:

{
  "filters": {
    "contacts": {
      "include": {
        "seniority": [4, 5],
        "departments": ["Engineering & Technical"],
        "signal": {
          "names": ["promotion", "companyChange"],
          "startDate": "2025-01-01"
        }
      }
    }
  },
  "pages": { "page": 0, "size": 25 }
}

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

DNC filtering (Scale feature)

excludeDnc is a Scale plan feature. Passing this parameter on an unsupported plan returns a 403 error.

Set "excludeDnc": true at the top level of the request body to filter out contacts whose phone numbers are all marked Do Not Call:

{
  "excludeDnc": true,
  "filters": {
    "contacts": {
      "include": {
        "seniority": [5],
        "departments": ["Sales"]
      }
    }
  },
  "pages": { "page": 0, "size": 25 }
}

When excludeDnc is enabled:

Contacts with at least one callable phone number remain in results.
Only callable phone numbers are shown - DNC numbers are hidden.
Contacts whose phones are all DNC are excluded entirely.

Example request

curl --request POST \
  --url https://api.lusha.com/prospecting/contact/search \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "contacts": {
        "include": {
          "jobTitles": ["VP of Engineering"],
          "seniority": [5],
          "departments": ["Engineering & Technical"],
          "locations": [{ "country": "United States" }]
        }
      },
      "companies": {
        "include": {
          "sizes": [{ "min": 201, "max": 1000 }]
        }
      }
    },
    "pages": { "page": 0, "size": 25 }
  }'

{
  "filters": {
    "contacts": {
      "include": {
        "jobTitles": ["VP of Engineering"],
        "seniority": [5],
        "departments": ["Engineering & Technical"],
        "locations": [{ "country": "United States" }]
      }
    },
    "companies": {
      "include": {
        "sizes": [{ "min": 201, "max": 1000 }]
      }
    }
  },
  "pages": { "page": 0, "size": 25 }
}

Example response

{
  "requestId": "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7",
  "currentPage": 0,
  "pageLength": 2,
  "totalResults": 142,
  "contacts": [
    {
      "contactId": "06de9b18-516d-5512-5cb5-6ec5pb215776",
      "name": "Chris Karageorge",
      "jobTitle": "Senior Director of Technical Operations",
      "companyId": 28054532,
      "companyName": "Lusha",
      "fqdn": "lusha.com",
      "isShown": false,
      "hasEmails": true,
      "hasWorkEmail": true,
      "hasPhones": true
    }
  ]
}

The requestId and each contact’s contactId are what you pass to the Enrich Contacts endpoint to retrieve full records. See the full API reference for the complete response schema, including all has* availability flags.

Use the Contact Filters endpoints to fetch valid values for seniority, departments, locations, and existing_data_points before building your search request.

Overview

Credits & Plans

Guides

Endpoints

Search prospecting contacts by ICP filters

Request body

Common filter fields

Signal filtering (premium feature)

DNC filtering (Scale feature)

Example request

Example response

​Request body

​Common filter fields

​Signal filtering (premium feature)

​DNC filtering (Scale feature)

​Example request

​Example response

Request body

Common filter fields

Signal filtering (premium feature)

DNC filtering (Scale feature)

Example request

Example response