---
title: "Prospecting Contacts"
method: POST
path: "/v3/contacts/prospecting"
tags: ["Prospecting"]
---

# Prospecting Contacts

`POST /v3/contacts/prospecting`

Search for contacts that match your Ideal Customer Profile using rich filter criteria.

**Filter by contact attributes:**
- Job title, seniority, department
- Location (city, state, country, continent)
- Existing data points (e.g. only contacts with a known work email)
- Signal activity (promotion, job change)

**Filter by company attributes:**
- Size, revenue, industry, technologies
- Location, intent topics, funding

Results are paginated up to 50,000 total (1,000 pages × 50 results). Use the returned contact `id` values with Enrich Contacts to reveal emails and phones.

> **Billing:** Charged per result via `api_search`. If signals are requested, an additional charge applies per matched signal per result.

> **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. This is additive — the primary response is unchanged, and a `tableWrite` object is added showing what happened on the table side. See [Contacts Tables](#tag/Contacts-Tables).

## Request body

- V3ProspectingContactsRequest
  - `pagination` V3PaginationRequest, required
    - `page` integer, required
    - `size` integer, required
  - `filters` V3ProspectingContactFilters, required
    - `contacts` object
      - `include` V3ContactFilterCriteria
        - `names` string[]
        - `jobTitles` string[]
        - `jobTitlesExactMatch` string[]
        - `normalizedJobTitles` string[]
        - `searchText` string
        - `countries` string[]
        - `locations` V3Location[]
          - `city` string
          - `state` string
          - `country` string
          - `continent` string
          - `countryGrouping` string
          - `region` string
          - `countryIso2` string
        - `seniorityIds` integer[]
        - `departments` string[]
        - `linkedinUrls` string[]
        - `existingDataPoints` string[]
        - `signals` object
          - `types` string[]
          - `startDate` string, date
        - `emails` string[] — Personal data — no catalog.
        - `previousEmails` string[] — Personal data — no catalog.
        - `previousJobTitle` string[]
        - `skills` string[]
        - `certifications` string[]
        - `awards` string[]
        - `ids` string[] — Encrypted contact id from a prior search's `results[].id`.
        - `existingDataPointsCondition` 'or' | 'and' — Pairs with `existingDataPoints`.
        - `jobChangedAfterDate` string, date — Refinement-only — must be paired with a base filter (e.g. `jobTitles`).
        - `jobChangedLastViewDate` string, date — Refinement-only — must be paired with a base filter.
        - `education` object — Refinement-only — must be paired with a base filter.
          - `degrees` string[]
          - `fieldsOfStudy` string[]
          - `schools` string[]
          - `startYearGte` integer
          - `graduationYearLte` integer
        - `score` object — Refinement-only — must be paired with a base filter. Raw 0–100 contact score. Distinct from the `confidence` band ("A+"/"A") returned on enriched contacts, which is derived from this score (e.g. `A+` when score > 75).
          - `minScore` integer
          - `maxScore` integer
        - `geographicDetails` object[]
          - `country` string
          - `zipcode` string
          - `distance` integer — Radius in miles.
      - `exclude` V3ContactFilterCriteria
        - `names` string[]
        - `jobTitles` string[]
        - `jobTitlesExactMatch` string[]
        - `normalizedJobTitles` string[]
        - `searchText` string
        - `countries` string[]
        - `locations` V3Location[]
          - `city` string
          - `state` string
          - `country` string
          - `continent` string
          - `countryGrouping` string
          - `region` string
          - `countryIso2` string
        - `seniorityIds` integer[]
        - `departments` string[]
        - `linkedinUrls` string[]
        - `existingDataPoints` string[]
        - `signals` object
          - `types` string[]
          - `startDate` string, date
        - `emails` string[] — Personal data — no catalog.
        - `previousEmails` string[] — Personal data — no catalog.
        - `previousJobTitle` string[]
        - `skills` string[]
        - `certifications` string[]
        - `awards` string[]
        - `ids` string[] — Encrypted contact id from a prior search's `results[].id`.
        - `existingDataPointsCondition` 'or' | 'and' — Pairs with `existingDataPoints`.
        - `jobChangedAfterDate` string, date — Refinement-only — must be paired with a base filter (e.g. `jobTitles`).
        - `jobChangedLastViewDate` string, date — Refinement-only — must be paired with a base filter.
        - `education` object — Refinement-only — must be paired with a base filter.
          - `degrees` string[]
          - `fieldsOfStudy` string[]
          - `schools` string[]
          - `startYearGte` integer
          - `graduationYearLte` integer
        - `score` object — Refinement-only — must be paired with a base filter. Raw 0–100 contact score. Distinct from the `confidence` band ("A+"/"A") returned on enriched contacts, which is derived from this score (e.g. `A+` when score > 75).
          - `minScore` integer
          - `maxScore` integer
        - `geographicDetails` object[]
          - `country` string
          - `zipcode` string
          - `distance` integer — Radius in miles.
    - `companies` object
      - `include` V3CompanyFilterCriteria
        - `names` string[]
        - `domains` string[]
        - `ids` string[]
        - `locations` V3Location[]
          - `city` string
          - `state` string
          - `country` string
          - `continent` string
          - `countryGrouping` string
          - `region` string
          - `countryIso2` string
        - `sizes` V3Range[]
          - `min` integer
          - `max` integer
        - `revenues` V3Range[]
          - `min` integer
          - `max` integer
        - `technologies` string[]
        - `technologiesCondition` 'or' | 'and'
        - `industriesLabels` string[]
        - `mainIndustriesIds` integer[]
        - `subIndustriesIds` integer[]
        - `intentTopics` string[]
        - `intentTopicsCondition` 'or' | 'and'
        - `intentMinScore` integer
        - `intentMaxScore` integer
        - `intentTopicsOperator` 'or' | 'and' | 'any' | 'all' — Recommended over `intentTopicsCondition`. `any`/`all` are aliases for `or`/`and`. `intentTopicsCondition` is not deprecated and remains accepted.
        - `topicCountThreshold` V3Range[]
          - `min` integer
          - `max` integer
        - `sicCodes` string[]
        - `naicsCodes` string[]
        - `funding` object — All funding sub-filters live under this single object. Every field is optional; combine any subset.
          - `isIpo` boolean
          - `ranges` object[]
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `min` integer
            - `max` integer
          - `date` object
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `date` string, date
          - `rounds` object[]
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `round` 'pre_seed' | 'seed' | 'series_a' | 'series_b' | 'series_c' | 'series_d' | 'series_e' | 'series_f' | 'series_g' | 'series_h' | 'other'
          - `names` object[]
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `name` 'angel' | 'venture' | 'private_equity' | 'crowdfunding' | 'grant' | 'debt_financing' | 'other'
          - `investors` string[] — Free text. Accepted but not currently applied downstream.
          - `types` string[] — Legacy free text. Accepted but not currently applied downstream.
        - `foundedYear` object[] — Filter by year the company was founded. Supports `min` (greater than or equal) and `max` (less than or equal) range operators.
          - `min` integer
          - `max` integer
        - `businessModel` string[] — Filter by business model. Accepted values: B2B, B2C, B2G.
        - `companyType` string[] — Filter by company type. Accepted values: Government, Private Company, Public Company, Educational, Non Profit, Self Employed.
        - `linkedinUrls` string[] — Filter by company LinkedIn URLs.
        - `keywords` string[] — Filter by keywords associated with the company.
        - `specialities` string[]
        - `exactSpecialities` string[]
        - `exactKeywords` string[]
        - `keywordsSearchFields` string[]
        - `previousCompanyDomains` string[]
        - `previousCompanyNames` string[]
        - `geographicDetails` object[]
          - `country` string
          - `zipcode` string
          - `distance` integer — Radius in miles.
        - `locationsZipcodes` object[]
          - `countryIso2` string
          - `zipcode` string
        - `headquarterZipcodes` object[]
          - `countryIso2` string
          - `zipcode` string
      - `exclude` V3CompanyFilterCriteria
        - `names` string[]
        - `domains` string[]
        - `ids` string[]
        - `locations` V3Location[]
          - `city` string
          - `state` string
          - `country` string
          - `continent` string
          - `countryGrouping` string
          - `region` string
          - `countryIso2` string
        - `sizes` V3Range[]
          - `min` integer
          - `max` integer
        - `revenues` V3Range[]
          - `min` integer
          - `max` integer
        - `technologies` string[]
        - `technologiesCondition` 'or' | 'and'
        - `industriesLabels` string[]
        - `mainIndustriesIds` integer[]
        - `subIndustriesIds` integer[]
        - `intentTopics` string[]
        - `intentTopicsCondition` 'or' | 'and'
        - `intentMinScore` integer
        - `intentMaxScore` integer
        - `intentTopicsOperator` 'or' | 'and' | 'any' | 'all' — Recommended over `intentTopicsCondition`. `any`/`all` are aliases for `or`/`and`. `intentTopicsCondition` is not deprecated and remains accepted.
        - `topicCountThreshold` V3Range[]
          - `min` integer
          - `max` integer
        - `sicCodes` string[]
        - `naicsCodes` string[]
        - `funding` object — All funding sub-filters live under this single object. Every field is optional; combine any subset.
          - `isIpo` boolean
          - `ranges` object[]
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `min` integer
            - `max` integer
          - `date` object
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `date` string, date
          - `rounds` object[]
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `round` 'pre_seed' | 'seed' | 'series_a' | 'series_b' | 'series_c' | 'series_d' | 'series_e' | 'series_f' | 'series_g' | 'series_h' | 'other'
          - `names` object[]
            - `coverage` 'last_funding' | 'any_round' | 'total_funds' | 'last_round'
            - `name` 'angel' | 'venture' | 'private_equity' | 'crowdfunding' | 'grant' | 'debt_financing' | 'other'
          - `investors` string[] — Free text. Accepted but not currently applied downstream.
          - `types` string[] — Legacy free text. Accepted but not currently applied downstream.
        - `foundedYear` object[] — Filter by year the company was founded. Supports `min` (greater than or equal) and `max` (less than or equal) range operators.
          - `min` integer
          - `max` integer
        - `businessModel` string[] — Filter by business model. Accepted values: B2B, B2C, B2G.
        - `companyType` string[] — Filter by company type. Accepted values: Government, Private Company, Public Company, Educational, Non Profit, Self Employed.
        - `linkedinUrls` string[] — Filter by company LinkedIn URLs.
        - `keywords` string[] — Filter by keywords associated with the company.
        - `specialities` string[]
        - `exactSpecialities` string[]
        - `exactKeywords` string[]
        - `keywordsSearchFields` string[]
        - `previousCompanyDomains` string[]
        - `previousCompanyNames` string[]
        - `geographicDetails` object[]
          - `country` string
          - `zipcode` string
          - `distance` integer — Radius in miles.
        - `locationsZipcodes` object[]
          - `countryIso2` string
          - `zipcode` string
        - `headquarterZipcodes` object[]
          - `countryIso2` string
          - `zipcode` string
  - `tableId` string — Optional. If provided, results are also persisted to this table. See the Tables API.
  - `options` object
    - `includePartialProfiles` boolean
    - `excludeDnc` boolean

## Response `200`

Successful response

- V3ProspectingContactsResponse
  - `requestId` string, uuid
  - `results` V3ContactPreview[]
    - `clientReferenceId` string
    - `id` string
    - `firstName` string
    - `lastName` string
    - `jobTitle` object
      - `title` string
      - `departments` string[]
      - `seniority` string
    - `company` object
      - `id` string
      - `name` string
      - `domain` string
    - `location` object
      - `country` string
      - `state` string
      - `city` string
    - `socialLinks` object
      - `linkedin` string
    - `has` string[]
    - `canReveal` V3CanRevealItem[]
      - `field` 'emails' | 'phones'
      - `credits` integer — Credit cost (0 when already revealed for this account)
    - `signalTypes` string[]
    - `error` V3ItemError — Per-item error in a batch response
      - `code` 'NOT_FOUND' | 'COMPLIANCE_RESTRICTED' | 'ENRICH_FAILED'
      - `message` string
  - `pagination` V3PaginationResponse
    - `page` integer
    - `size` integer
    - `total` integer
  - `tableWrite` TableWrite — Added to a Prospecting, Enrich, Signals, or Lookalike response when `tableId` is passed on the request. The primary response is unaffected even if the table write fails.
    - `tableId` string
    - `added` integer — Number of new entities added to the table by this call.
    - `alreadyPresent` integer — Number of entities from this call that were already in the table.
    - `columnsCreated` integer — Number of columns auto-created by this call (e.g. a Signals column created on first use).
    - `rowsProcessed` integer — Number of rows the column-run touched as part of this call.
    - `rowsCharged` integer — Number of those rows that incurred a credit charge.
    - `rowsAlreadyPaidInTable` integer — Number of those rows that were already paid for in this table and were not re-charged.
    - `creditsCharged` integer — Credits charged specifically for this table write.
  - `billing` V3Billing — Credit usage summary for a V3 API request
    - `creditsCharged` integer — Total credits charged for this request
    - `resultsReturned` integer — Number of successful results returned

## Other responses

- `400` — Bad request - invalid input data
- `401` — Unauthorized - invalid or missing API key
- `402` — Payment required - insufficient credits
- `403` — Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
- `429` — Too many requests - rate limit exceeded

---

[API](https://skmtc.net/lusha/apis/lusha-api-documentation.md) · [All operations](https://skmtc.net/lusha/apis/lusha-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lusha/lusha-api-documentation/revisions/4c51e40e3e67/schema)