> ## 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 attributes - to get a paginated list of contact previews.

`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](/api-reference/enrich/enrich-contacts).

Before building your request, use the [contact filter types](/api-reference/filters/contact-filter-types) and [contact filter values](/api-reference/filters/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`.

```json theme={null}
{
  "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](/api-reference/filters/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](/api-reference/prospecting/prospecting-contacts) 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.

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

Add a `signals` object under `filters.contacts.include`:

```json theme={null}
{
  "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:

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

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  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 }
    }'
  ```

  ```json Request body theme={null}
  {
    "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 }
  }
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "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](/api-reference/enrich/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](/api-reference/prospecting/prospecting-contacts) for the complete response schema.

<Tip>
  Use the [contact filter types](/api-reference/filters/contact-filter-types) and [contact filter values](/api-reference/filters/contact-filter-values) endpoints to fetch valid values for `seniorityIds`, `departments`, `locations`, and `existingDataPoints` before building your search request.
</Tip>