# Prospecting Contacts

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.

Endpoint: POST /v3/contacts/prospecting
Security: ApiKeyAuth

## Request fields (application/json):

  - `pagination` (object, required)

  - `pagination.page` (integer, required)

  - `pagination.size` (integer, required)
    Example: 25

  - `filters` (object, required)

  - `filters.contacts` (object)

  - `filters.contacts.include` (object)

  - `filters.contacts.include.names` (array)

  - `filters.contacts.include.jobTitles` (array)
    Example: ["VP Sales","Director of Sales"]

  - `filters.contacts.include.jobTitlesExactMatch` (array)

  - `filters.contacts.include.normalizedJobTitles` (array)

  - `filters.contacts.include.searchText` (string)

  - `filters.contacts.include.countries` (array)
    Example: ["US","CA"]

  - `filters.contacts.include.locations` (array)

  - `filters.contacts.include.locations.city` (string)
    Example: "San Francisco"

  - `filters.contacts.include.locations.state` (string)
    Example: "California"

  - `filters.contacts.include.locations.country` (string)
    Example: "United States"

  - `filters.contacts.include.locations.continent` (string)
    Example: "North America"

  - `filters.contacts.include.locations.countryGrouping` (string)
    Example: "EMEA"

  - `filters.contacts.include.seniorityIds` (array)
    Example: [4,5]

  - `filters.contacts.include.departments` (array)
    Example: ["Sales","Engineering"]

  - `filters.contacts.include.linkedinUrls` (array)

  - `filters.contacts.include.existingDataPoints` (array)
    Example: ["work_email","work_phone"]

  - `filters.contacts.include.signals` (object)

  - `filters.contacts.include.signals.types` (array)
    Enum: "allSignals", "promotion", "companyChange"

  - `filters.contacts.include.signals.startDate` (string)

  - `filters.contacts.exclude` (object)

  - `filters.companies` (object)

  - `options` (object)

  - `options.includePartialProfiles` (boolean)

  - `options.excludeDnc` (boolean)

## Response 200 fields (application/json):

  - `requestId` (string)

  - `results` (array)

  - `results.clientReferenceId` (string)
    Example: "my-ref-1"

  - `results.id` (string)
    Example: "4389064704"

  - `results.firstName` (string)
    Example: "Orit"

  - `results.lastName` (string)
    Example: "Shilvock"

  - `results.jobTitle` (object)

  - `results.jobTitle.title` (string)
    Example: "Vice President of Partnerships"

  - `results.jobTitle.departments` (array)
    Example: ["Business Development"]

  - `results.jobTitle.seniority` (string)
    Example: "Vice President"

  - `results.company` (object)

  - `results.company.name` (string)
    Example: "Lusha"

  - `results.company.domain` (string)
    Example: "www.lusha.com"

  - `results.location` (object)

  - `results.location.country` (string)
    Example: "Israel"

  - `results.location.state` (string)
    Example: "Tel Aviv District"

  - `results.location.city` (string)
    Example: "Tel Aviv"

  - `results.socialLinks` (object)

  - `results.socialLinks.linkedin` (string)
    Example: "https://www.linkedin.com/in/orit-shilvock-6243bb5"

  - `results.has` (array)
    Example: ["firstName","lastName","jobTitle","location","socialLinks","emails"]

  - `results.canReveal` (array)

  - `results.canReveal.field` (string)
    Enum: "emails", "phones"

  - `results.canReveal.credits` (integer)
    Credit cost (0 when already revealed for this account)
    Example: 1

  - `results.signalTypes` (array)
    Example: ["promotion","companyChange"]

  - `results.error` (object)
    Per-item error in a batch response

  - `results.error.code` (string)
    Enum: "NOT_FOUND", "COMPLIANCE_RESTRICTED", "ENRICH_FAILED"

  - `results.error.message` (string)
    Example: "Contact not found"

  - `pagination` (object)

  - `pagination.page` (integer)

  - `pagination.size` (integer)
    Example: 25

  - `pagination.total` (integer)
    Example: 150

  - `billing` (object)
    Credit usage summary for a V3 API request

  - `billing.creditsCharged` (integer)
    Total credits charged for this request
    Example: 3

  - `billing.resultsReturned` (integer)
    Number of successful results returned
    Example: 1

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 401 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 402 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 403 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 429 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]