> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search prospecting contacts by ICP filters
> Query Lusha's contact database by ICP filters - job title, seniority, department, location, and company size - to get a list of matching contact IDs.
`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](/v2/prospecting/enrich-contacts).
Before building your request, use the [Contact Filters](/v2/filters/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.
```json theme={null}
{
"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](/v2/filters/contact-filters) for valid values |
| `filters.contacts.include.departments` | string\[] | Department names - use [GET /prospecting/filters/contacts/departments](/v2/filters/contact-filters) |
| `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](/v2/filters/contact-filters) |
| `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](/v2/filters/company-filters) |
| `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](#dnc-filtering-scale-feature) 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
```bash cURL theme={null}
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 }
}'
```
```json Request body theme={null}
{
"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
```json theme={null}
{
"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](/v2/prospecting/enrich-contacts) endpoint to retrieve full records. See the [full API reference](/v2/api-reference/prospecting/search-contacts) for the complete response schema, including all `has*` availability flags.
Use the [Contact Filters](/v2/filters/contact-filters) endpoints to fetch valid values for `seniority`, `departments`, `locations`, and `existing_data_points` before building your search request.