# Search Contacts

Search for contacts using various filters. This is step 2 of the prospecting process.

Endpoint: (POST)  https://api.lusha.com/prospecting/contact/search
---
##### Signal Filtering (Premium Feature)
Filter contacts by signal types to find prospects at key career moments.

  > Note: This is a premium feature. Credits are charged for each signal type that returns results.

---
##### DNC Filtering (Scale Feature)
Use excludeDnc: true at the top level of the request body to filter 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 shown — DNC phones are hidden - Contacts with only DNC phones are excluded entirely
> Note: Returns 403 on unsupported plans.

Endpoint: POST /prospecting/contact/search
Security: ApiKeyAuth

## Request fields (application/json):

  - `includePartialContact` (boolean)
    When set to true, includes contacts with partial information in the search results.

  - `excludeDnc` (boolean)
    When true, excludes contacts whose phones are all marked Do Not Call (DNC).
    Example: true

  - `pages` (object)

  - `pages.page` (number)
    Page number (0-1000)

  - `pages.size` (number)
    Page size (10-50)

  - `filters` (object, required)

  - `filters.contacts` (object)

  - `filters.contacts.include` (object)

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

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

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

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

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

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

  - `filters.contacts.include.locations.city` (string)
    Example: "New York"

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

  - `filters.contacts.include.locations.country_grouping` (string)
    Example: "na"

  - `filters.contacts.include.jobTitles` (array)
    Example: ["CTO","Chief Technology Officer","VP Engineering","Senior Developer"]

  - `filters.contacts.include.linkedinUrls` (array)
    Filter contacts by LinkedIn profile URLs
    Example: ["https://www.linkedin.com/in/justin-pernitz","https://www.linkedin.com/in/andrewbarrettbettcher"]

  - `filters.contacts.include.searchText` (string)
    Free-text search across contact fields
    Example: "Amit"

  - `filters.contacts.include.signal` (object)
    Filter contacts by signal types (premium filter - charges apply per signal type)

  - `filters.contacts.include.signal.names` (array)
    Signal types to filter by
    Enum: "allSignals", "promotion", "companyChange"

  - `filters.contacts.include.signal.startDate` (string)
    Start date for signal detection (YYYY-MM-DD format)
    Example: "2025-11-01"

  - `filters.companies` (object)

  - `filters.companies.include` (object)

  - `filters.companies.include.names` (array)
    Example: ["Apple"]

  - `filters.companies.include.domains` (array)
    Example: ["lusha.com"]

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

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

  - `filters.companies.include.technologies` (array)
    Example: [{"name":"Amazon"}]

  - `filters.companies.include.technologies.name` (string, required)
    Example: "salesforce"

  - `filters.companies.include.intentTopics` (array)
    Example: ["Digital Sales"]

  - `filters.companies.include.sizes` (array)

  - `filters.companies.include.sizes.min` (number)
    Example: 1

  - `filters.companies.include.sizes.max` (number)
    Example: 10

  - `filters.companies.include.revenues` (array)

  - `filters.companies.include.revenues.min` (number)
    Example: 1

  - `filters.companies.include.revenues.max` (number)
    Example: 1000000

  - `filters.companies.include.sicCodes` (array)
    Example: ["1011","1021"]

  - `filters.companies.include.naicsCodes` (array)
    Example: ["11","21"]

  - `filters.companies.include.mainIndustriesIds` (array)
    Example: [4,5]

  - `filters.companies.include.subIndustriesIds` (array)
    Example: [101]

  - `filters.companies.include.searchText` (string)
    Free-text search across company fields
    Example: "Finance Marketing in Germany DE"

  - `filters.companies.include.excludePartialCompanies` (boolean)

  - `filters.companies.include.companyLocations` (array)
    Filter by company site-level office locations as reported by LinkedIn.
This includes all physical office locations where the company has a presence.
    Example: [{"country":"United States","state":"California"},{"country":"Germany"}]

  - `filters.companies.include.companyLocations.country` (string, required)
    Example: "United States"

  - `filters.companies.include.companyLocations.state` (string)
    Example: "California"

  - `filters.companies.include.employeesInLinkedIn` (object)
    Filter companies by LinkedIn-reported employee count.
Both min and max are optional — provide either or both.

  - `filters.companies.include.employeesInLinkedIn.min` (integer)
    Minimum employee count (inclusive)
    Example: 100

  - `filters.companies.include.employeesInLinkedIn.max` (integer)
    Maximum employee count (inclusive)
    Example: 5000

  - `filters.companies.include.signal` (object)
    Filter companies by signal types (premium filter - charges apply per signal type).

  - `filters.companies.include.signal.names` (array)
    Signal types to filter by
    Enum: "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews"

  - `filters.companies.include.signal.startDate` (string)
    Start date for signal detection (YYYY-MM-DD format)
    Example: "2025-11-01"

  - `filters.companies.exclude` (object)
    Same structure as include, for exclusion filters

## Response 200 fields (application/json):

  - `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` (array)

  - `contacts.contactId` (string)
    A unique serial contact ID generated for each search response
    Example: "06de9b18-516d-5512-5cb5-6ec5pb215776"

  - `contacts.isShown` (boolean)
    Indicates whether the contact was already revealed by any of the account users

  - `contacts.name` (string)
    The full name of the contact
    Example: "Chris Karageorge"

  - `contacts.jobTitle` (string)
    The job title held by the person at their current company
    Example: "Senior Director of Technical Operations"

  - `contacts.companyId` (number)
    A unique identifier for a Lusha company
    Example: 28054532

  - `contacts.companyName` (string)
    The name of the company where the person currently works
    Example: "Lusha"

  - `contacts.fqdn` (string)
    The fqdn of the company
    Example: "lusha.com"

  - `contacts.hasCompanyEmployeesCount` (boolean)

  - `contacts.hasCompanyRevenue` (boolean)

  - `contacts.hasCompanyMainIndustry` (boolean)

  - `contacts.hasCompanySubIndustry` (boolean)

  - `contacts.hasCompanyFunding` (boolean)

  - `contacts.hasCompanyIntent` (boolean)

  - `contacts.hasCompanyTechnologies` (boolean)

  - `contacts.hasDepartment` (boolean)

  - `contacts.hasSeniority` (boolean)

  - `contacts.hasContactLocation` (boolean)

  - `contacts.hasSocialLink` (boolean)

  - `contacts.hasEmails` (boolean)

  - `contacts.hasWorkEmail` (boolean)

  - `contacts.hasPrivateEmail` (boolean)

  - `contacts.hasPhones` (boolean)

  - `contacts.hasMobilePhone` (boolean)

  - `contacts.hasDirectPhone` (boolean)

  - `contacts.hasCompanyCity` (boolean)

  - `contacts.hasCompanyCountry` (boolean)

  - `contacts.signalTypes` (array)
    Types of signals detected for this contact
    Example: ["companyChange","promotion"]

## 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"]