POST /prospecting/contact/search - Search contacts

POST

prospecting

contact

curl --request POST \
  --url https://api.lusha.com/prospecting/contact/search \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "pages": {
    "page": 0,
    "size": 20
  },
  "filters": {
    "contacts": {
      "include": {
        "departments": [
          "Engineering & Technical",
          "Marketing"
        ],
        "seniority": [
          4,
          5
        ],
        "existing_data_points": [
          "phone",
          "work_email",
          "mobile_phone"
        ],
        "locations": [
          {
            "continent": "North America",
            "country": "United States",
            "city": "New York",
            "state": "New York",
            "country_grouping": "na"
          }
        ],
        "signals": {
          "names": [
            "allSignals",
            "promotion",
            "companyChange"
          ],
          "startDate": "2025-11-01"
        }
      },
      "exclude": {
        "departments": [
          "Human Resources"
        ]
      }
    },
    "companies": {
      "include": {
        "names": [
          "Apple",
          "Microsoft"
        ],
        "locations": [
          {
            "country": "United States"
          }
        ],
        "technologies": [
          "Salesforce",
          "Amazon Web Services"
        ],
        "mainIndustriesIds": [
          4,
          5
        ],
        "subIndustriesIds": [
          101
        ],
        "intentTopics": [
          "Digital Sales"
        ],
        "sizes": [
          {
            "min": 100,
            "max": 1000
          }
        ],
        "revenues": [
          {
            "min": 10000000,
            "max": 100000000
          }
        ],
        "sicCodes": [
          "1011",
          "1021"
        ],
        "naicsCodes": [
          "11",
          "21"
        ]
      },
      "exclude": {}
    }
  }
}
'

{
  "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,
      "hasMobilePhone": true,
      "hasDirectPhone": false,
      "signalTypes": ["promotion"]
    }
  ]
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["filters is required"]
}

{
  "statusCode": 403,
  "message": "Forbidden",
  "errors": ["excludeDnc is not available on your current plan"]
}

Use this endpoint to query Lusha’s contact database with filters aligned to your Ideal Customer Profile. You get back a list of matching contacts with IDs you then pass to the Enrich Contacts endpoint to retrieve full details. This is step 2 of the three-step prospecting flow.

Prospecting flow

Step	Endpoint	Purpose
1	Filters API	Discover valid filter values for your search
2	POST /prospecting/contact/search	Query contacts using your filters
3	POST /prospecting/contact/enrich	Retrieve full contact details by ID

Endpoint

POST https://api.lusha.com/prospecting/contact/search

Authentication: API key (ApiKeyAuth)

Request body

object

required

The top-level filter container. At least the filters object is required.

Show filters.contacts

object

Criteria that matching contacts must satisfy.

Show include fields

string[]

Free-text job titles to match. Example: ["CTO", "VP Engineering", "Senior Developer"]

number[]

Seniority level IDs. Example: [4, 5]

string[]

Department names. Example: ["Engineering & Technical"]

object[]

Geographic filters. Each object may include continent, country, state, city, and country_grouping.

string[]

Only return contacts that have specific data available. Example values: "phone", "work_email", "mobile_phone", "direct_phone". See Contact filters for the full list of valid values.

string[]

Filter by specific LinkedIn profile URLs.

string

Free-text search across contact fields. Example: "Amit"

object

Premium feature. Filter contacts that have a signal of the specified types. Credits are charged for each signal type that returns results.

Show signal fields

string[]

Signal types to match. Allowed values: "allSignals", "promotion", "companyChange"

string

Earliest signal date in YYYY-MM-DD format. Example: "2025-01-01"

object

Same structure as include. Contacts matching these criteria are excluded from results.

Show filters.companies

object

Company-level include criteria. Same exclusion structure is available under filters.companies.exclude.

object

Pagination controls.

Show pages fields

number

default:"0"

Page number. Range: 0–1000.

number

default:"20"

Results per page. Range: 10–50.

boolean

When true, includes contacts with incomplete data in results. Partial profiles may lack some contact details but can still be useful prospects.

boolean

Scale plan feature. When true, filters out contacts whose phone numbers are all marked Do Not Call.

Contacts with at least one callable phone appear in results.
Only callable phones are returned - DNC phones are hidden.
Contacts with only DNC phones are excluded entirely.

Returns 403 on unsupported plans.

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": ["CTO", "Chief Technology Officer", "VP Engineering"],
          "seniority": [4, 5],
          "departments": ["Engineering & Technical"],
          "locations": [
            { "country": "United States", "state": "New York" }
          ],
          "existing_data_points": ["work_email"]
        }
      }
    },
    "pages": { "page": 0, "size": 25 },
    "excludeDnc": true
  }'

{
  "filters": {
    "contacts": {
      "include": {
        "jobTitles": ["CTO", "Chief Technology Officer", "VP Engineering"],
        "seniority": [4, 5],
        "departments": ["Engineering & Technical"],
        "locations": [
          { "country": "United States", "state": "New York" }
        ],
        "existing_data_points": ["work_email"],
        "signal": {
          "names": ["promotion"],
          "startDate": "2025-01-01"
        }
      }
    }
  },
  "pages": { "page": 0, "size": 25 },
  "excludeDnc": true
}

Response

200 - Success

string

Unique ID for this search. Pass this value to the Enrich Contacts endpoint as requestId.

number

The page number returned.

number

Number of results on this page.

number

Total number of contacts matching your filters across all pages.

object[]

Array of matching contacts.

Show contact fields

string

Unique serial ID for this contact in this search response. Use this ID in the Enrich endpoint. Example: "06de9b18-516d-5512-5cb5-6ec5pb215776"

string

Full name of the contact. Example: "Chris Karageorge"

string

Current job title. Example: "Senior Director of Technical Operations"

number

Lusha company identifier. Example: 28054532

string

Name of the contact’s current employer. Example: "Lusha"

string

Company domain. Example: "lusha.com"

string

Description of the contact’s current company.

string

URL of the company’s logo.

boolean

Whether this contact has already been revealed by any user in your account.

string[]

Signal types detected for this contact. Example: ["promotion", "companyChange"]

boolean

Whether this contact has email addresses available.

boolean

Whether this contact has phone numbers available.

boolean

Whether a mobile phone is available.

boolean

Whether a direct phone number is available.

boolean

Whether a work email is available.

boolean

Whether a personal email is available.

boolean

Whether department data is available for this contact.

boolean

Whether seniority data is available for this contact.

boolean

Whether location data is available for this contact.

Whether a social profile link (e.g. LinkedIn) is available for this contact.

boolean

Whether the company’s headcount is available.

boolean

Whether the company’s revenue range is available.

boolean

Whether the company’s main industry classification is available.

boolean

Whether the company’s sub-industry classification is available.

boolean

Whether the company’s funding data is available.

boolean

Whether the company’s buyer intent data is available.

boolean

Whether the company’s technology stack data is available.

boolean

Whether the company’s city is available.

boolean

Whether the company’s country is available.

Error codes

Status	Meaning
`400`	Validation failed - check your request body for missing or invalid fields.
`401`	Unauthorized - your API key is missing or invalid.
`403`	Forbidden - your plan does not support this feature (e.g., `excludeDnc` on non-Scale plans, or signal filtering).
`429`	Too many requests - you have exceeded the rate limit.
`500`	Internal server error - retry with exponential backoff.

{
  "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,
      "hasMobilePhone": true,
      "hasDirectPhone": false,
      "signalTypes": ["promotion"]
    }
  ]
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["filters is required"]
}

{
  "statusCode": 403,
  "message": "Forbidden",
  "errors": ["excludeDnc is not available on your current plan"]
}

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.

Body

application/json

filters

object

required

Show child attributes

includePartialContact

boolean

default:true

When set to true, includes contacts with partial information in the search results. Partial contacts may have incomplete data but can still be valuable prospects.

Example:

false

excludeDnc

boolean

default:false

When true, excludes contacts whose phones are all marked Do Not Call (DNC). Contacts with at least one callable phone appear in results; only callable phones are returned (DNC phones are hidden). Contacts with only DNC phones are excluded entirely.

Example:

true

pages

object

Show child attributes

Response

Search results with contact IDs

requestId

string

The unique request ID used for subsequent enrichment requests

currentPage

number

The current page of the search results

pageLength

number

The number of results on the page

totalResults

number

The total number of search results

contacts

object[]

Show child attributes

⌘I

curl --request POST \
  --url https://api.lusha.com/prospecting/contact/search \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "pages": {
    "page": 0,
    "size": 20
  },
  "filters": {
    "contacts": {
      "include": {
        "departments": [
          "Engineering & Technical",
          "Marketing"
        ],
        "seniority": [
          4,
          5
        ],
        "existing_data_points": [
          "phone",
          "work_email",
          "mobile_phone"
        ],
        "locations": [
          {
            "continent": "North America",
            "country": "United States",
            "city": "New York",
            "state": "New York",
            "country_grouping": "na"
          }
        ],
        "signals": {
          "names": [
            "allSignals",
            "promotion",
            "companyChange"
          ],
          "startDate": "2025-11-01"
        }
      },
      "exclude": {
        "departments": [
          "Human Resources"
        ]
      }
    },
    "companies": {
      "include": {
        "names": [
          "Apple",
          "Microsoft"
        ],
        "locations": [
          {
            "country": "United States"
          }
        ],
        "technologies": [
          "Salesforce",
          "Amazon Web Services"
        ],
        "mainIndustriesIds": [
          4,
          5
        ],
        "subIndustriesIds": [
          101
        ],
        "intentTopics": [
          "Digital Sales"
        ],
        "sizes": [
          {
            "min": 100,
            "max": 1000
          }
        ],
        "revenues": [
          {
            "min": 10000000,
            "max": 100000000
          }
        ],
        "sicCodes": [
          "1011",
          "1021"
        ],
        "naicsCodes": [
          "11",
          "21"
        ]
      },
      "exclude": {}
    }
  }
}
'

{
  "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,
      "hasMobilePhone": true,
      "hasDirectPhone": false,
      "signalTypes": ["promotion"]
    }
  ]
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["filters is required"]
}

{
  "statusCode": 403,
  "message": "Forbidden",
  "errors": ["excludeDnc is not available on your current plan"]
}

​Endpoint

​Request body

​Example request

​Response

​200 - Success

​Error codes

Authorizations

Body

Response

Endpoint

Request body

Example request

Response

200 - Success

Error codes