Find contacts or companies from known identifiers — contact id, LinkedIn URL, email or name + company; company id, name or domain — and return a non-PII preview with `has` and `canReveal` fields describing what exists and what can be unlocked.
openapi: 3.2.0
info:
title: Lusha API Documentation Search API
version: ''
x-logo:
url: https://www.lusha.com/logo.png
license:
name: Proprietary
url: https://lusha.com/legal/terms
description: "<blockquote class=\"callout\">\n\n **This is the Lusha API V3 documentation.** \n \n V3 introduces a new search-then-enrich pattern, bulk operations, AI-powered lookalikes, and richer filter capabilities. All endpoints are under `https://api.lusha.com/v3/`.\n\n For more information on V3, refer to the [Migration Guide](/tutorials/v3-migration-guide).\n\n</blockquote>\n\n --- \n\nLusha provides a RESTful API for querying a comprehensive dataset of business profiles and company information. Built for teams running prospecting, enrichment, automation, and analytics workflows that need accurate, continuously updated business data. The API supports both real-time and bulk use cases.\n\nUse the Lusha API to **search for new prospects**, **enrich existing records**, **react to real-world changes**, and **expand coverage** with AI-powered lookalike recommendations.\n\n> All API requests must be made over **HTTPS**. All responses are returned in **JSON** format.\n\n--- \n## Available Endpoints\n\n| Category | Description |\n|---|---|\n| [**Search**](#tag/Search) | Find contacts or companies using known identifiers |\n| [**Enrich**](#tag/Enrich) | Retrieve full profile data for contacts or companies by ID |\n| [**Search & Enrich**](#tag/Search-and-Enrich) | Find and retrieve full contact or company data in a single call |\n| [**Prospecting**](#tag/Prospecting) | Filter-based search across contacts and companies |\n| [**Lookalikes**](#tag/Lookalikes) | AI-powered recommendations for similar contacts and companies |\n| [**Buying Group**](#tag/Buying-Group) | Identify decision makers, champions, and end users within target accounts |\n| [**Contacts Tables**](#tag/Contacts-Tables) | Persist, organize, and enrich contacts in reusable tables |\n| [**Companies Tables**](#tag/Companies-Tables) | Persist, organize, and enrich companies in reusable tables |\n| [**Signals**](#tag/Signals) | Real-world activity data for contacts and companies |\n| [**Website Visitors**](#tag/Website-Visits) | Companies ranked by website-visit signals for your tracked domains |\n| [**Filters**](#tag/Filters) | Discover valid filter values for prospecting |\n| [**Webhooks**](#tag/Webhooks) | Real-time signal notifications via HTTP callbacks |\n| [**Account**](#tag/Account) | Usage, credits, rate limits, and pricing |\n\n<blockquote class=\"callout\">\n\n **Waterfall Reveal for Contact Enrichment.**\n\n Enrich Contacts now supports `waterfallEnabled`. Fall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts. On by default once your account has it turned on - pass `waterfallEnabled: false` to opt a specific call out. [See Enrich Contacts](#operation/enrichContacts).\n\n</blockquote>\n\n---\n\n## Data Source and Privacy\n\n**Lusha is a search platform.** The data provided is not created or directly managed by Lusha. It is sourced from publicly available information and trusted business partners.\n\nFor more details on how we collect and handle data, see our [Privacy Policy](https://lusha.com/legal/privacy-notice/).\n\n---\n\n## Authentication\n\nAll API requests require an **API key** linked to your Lusha account and plan. Pass your key in the `api_key` request header on every call.\n\n> Generate and manage your API key in the [Lusha dashboard](https://dashboard.lusha.com/enrich/api).\n\nStore your API key securely and use it only in **server-side environments**.\n\n---\n\n## Rate Limiting\n\nLusha enforces rate limits on a per-plan basis to ensure fair usage and platform stability. Limits are applied across multiple time windows (per minute, per hour, and per day), and vary depending on your account plan.\n\nRate limits for the **Credit Usage API** differ from standard endpoint limits.\n\n> **Note:** To check your current plan's limits, visit the [Lusha Help Center](https://info.lusha.com/en/articles/163856-all-there-is-to-know-about-lusha-s-api) or contact your account manager.\n\n**Rate Limit Response Headers**\n\n| Header | Description |\n|--------|-------------|\n| `x-rate-limit-daily` | Total requests allowed per day |\n| `x-daily-requests-left` | Requests remaining in your daily quota |\n| `x-daily-usage` | Requests made in the current daily period |\n| `x-rate-limit-hourly` | Total requests allowed per hour |\n| `x-hourly-requests-left` | Requests remaining in your hourly quota |\n| `x-hourly-usage` | Requests made in the current hourly period |\n| `x-rate-limit-minute` | Total requests allowed per minute |\n| `x-minute-requests-left` | Requests remaining in the current minute window |\n| `x-minute-usage` | Requests made in the current minute window |\n\n---\n## Error Codes\n\nLusha uses standard HTTP status codes to indicate the result of each request.\n\n| Code | Name | Description |\n|------|------|-------------|\n| `200` | OK | Request was successful |\n| `400` | Bad Request | Request is malformed or missing required fields |\n| `401` | Unauthorized | API key is missing or invalid |\n| `402` | Payment Required | Insufficient credits or payment needed |\n| `403` | Forbidden | Account is inactive. Contact support@lusha.com |\n| `404` | Not Found | Endpoint or resource does not exist |\n| `429` | Too Many Requests | Rate limit or daily quota exceeded |\n| `451` | Unavailable For Legal Reasons | Request blocked due to GDPR regulations |\n| `499` | Client Closed Request | Request timed out before completing |\n| `5XX` | Server Error | Issue on Lusha's end. Retry with exponential backoff |\n\n**Error Response Format**\n\n```json\n{\n \"statusCode\": 400,\n \"message\": \"Invalid request parameters\"\n}\n```\n\n**Tables-specific error codes**\n\n| Code | Status | Meaning |\n|---|---|---|\n| `TABLE_NOT_FOUND` | 404 | The `table_id` does not exist or is not accessible to this account |\n| `COLUMN_NOT_FOUND` | 404 | The `column_id` does not exist on the given table |\n| `TABLE_NAME_CONFLICT` | 409 | A table with this name already exists |\n\nTables error bodies use the shape `{ \"message\": \"...\", \"code\": <status>, ... }` rather than the `statusCode`/`errors` shape used elsewhere in this doc.\n\n**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities per table · max 500 tables per account · `page` 0–100 · `size` default 100.\n\n**Tips for Handling Errors**\n\n- Verify your API key is correct and active\n- Read the `message` field for specific troubleshooting details\n- For `429` errors, wait before retrying\n- For `5XX` errors, use exponential backoff before retrying\n"
contact:
name: Lusha Support
url: https://api.lusha.com
email: support@lusha.com
termsOfService: https://lusha.com/legal/terms
x-privacy-policy:
name: Privacy Policy
url: https://lusha.com/legal/privacy-notice/
servers:
- url: https://api.lusha.com
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Search
description: '**Search APIs:** Find contacts or companies using known identifiers.
Look up contacts by `id`, `linkedinUrl`, `email`, or `firstName` + `lastName` + `companyName`/`companyDomain`. Look up companies by `id`, `name`, or `domain`.
Returns a non-PII preview of each profile with a `has` field listing available data points and a `canReveal` field showing what can be unlocked via Enrich.
> **Billing:** Charged per successful result via the `api_search` action.
'
x-tag-expanded: true
paths:
/v3/contacts/search:
post:
tags:
- Search
summary: Search Contacts
operationId: searchContacts
description: 'Look up contacts by identifier. Returns a non-PII preview of each profile — no emails or phone numbers.
**Accepted identifiers (one required per contact):**
- Lusha contact `id`
- `linkedinUrl`
- `email`
- `firstName` + `lastName` + `companyName` or `companyDomain`
Up to 100 contacts per request. Each result includes:
- `has` — data points available on this profile
- `canReveal` — what you can unlock via Enrich Contacts, and the credit cost
Pass a `signals` filter to narrow results to contacts with recent activity (e.g. promotion, job change).
> **Billing:** Charged per successful result via the `api_search` action.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V3ContactsSearchRequest'
example:
contacts:
- clientReferenceId: my-ref-1
firstName: Orit
lastName: Shilvock
companyName: Lusha
companyDomain: lusha.com
- clientReferenceId: my-ref-2
linkedinUrl: https://www.linkedin.com/in/shmulikwillinger
- clientReferenceId: my-ref-3
email: gal.ashkelon@lusha.com
- clientReferenceId: my-ref-4
id: '12345'
options:
includePartialProfiles: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/V3ContactsSearchResponse'
example:
requestId: 6e4b1192-9440-42c4-9a3e-793ddef6d73c
results:
- clientReferenceId: my-ref-1
id: '4415824633'
firstName: Orit
lastName: Shilvock
jobTitle:
title: Vice President of Partnerships
departments:
- Business Development
seniority: Vice President
company:
id: '16303253'
name: Lusha
domain: www.lusha.com
industry: Technology, Information & Media
location:
country: Israel
city: Tel Aviv
socialLinks:
linkedin: https://www.linkedin.com/in/orit-shilvock-6243bb5
has:
- firstName
- lastName
- jobTitle
- location
- socialLinks
- emails
canReveal:
- field: emails
credits: 1
- clientReferenceId: my-ref-2
id: '4415824679'
firstName: Shmulik
lastName: Willinger
jobTitle:
title: Chief Architect
departments:
- Engineering & Technical
seniority: C-Suite
company:
id: '16303253'
name: Lusha
domain: www.lusha.com
industry: Technology, Information & Media
location:
country: Israel
city: Tel Aviv
socialLinks:
linkedin: https://www.linkedin.com/in/shmulikwillinger
has:
- firstName
- lastName
- jobTitle
- location
- socialLinks
- emails
canReveal:
- field: emails
credits: 1
- clientReferenceId: my-ref-3
id: '4415824664'
firstName: Gal
lastName: Ashkelon
jobTitle:
title: Global Partner Program Manager
departments:
- Business Development
seniority: Manager
company:
id: '16303253'
name: Lusha
domain: www.lusha.com
industry: Technology, Information & Media
location:
country: Israel
city: Tel Aviv
socialLinks:
linkedin: https://www.linkedin.com/in/gal-ashkelon-39408557
has:
- firstName
- lastName
- jobTitle
- location
- socialLinks
- emails
canReveal:
- field: emails
credits: 1
- clientReferenceId: my-ref-4
error:
code: NOT_FOUND
message: Contact not found
billing:
creditsCharged: 1
resultsReturned: 3
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/v3/companies/search:
post:
tags:
- Search
summary: Search Companies
operationId: searchCompanies
description: 'Look up companies by identifier. Returns a preview of each company profile.
**Accepted identifiers (at least one required per company):**
- Lusha company `id`
- `name`
- `domain`
Up to 100 companies per request. Each result includes a `has` field listing the data available via Enrich Companies.
Pass a `signals` filter to narrow results to companies showing specific activity (e.g. headcount growth, hiring surge).
> **Billing:** Charged per successful result via the `api_search` action.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V3CompaniesSearchRequest'
example:
companies:
- clientReferenceId: comp-ref-1
name: Lusha
- clientReferenceId: comp-ref-2
domain: salesforce.com
- clientReferenceId: comp-ref-3
id: '16303253'
options:
includePartialProfiles: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/V3CompaniesSearchResponse'
example:
requestId: abd4a213-d33b-4565-b9b6-55c19c65cc47
results:
- clientReferenceId: comp-ref-1
id: '16303253'
name: Lusha
domain: www.lusha.com
employeeCount:
exact: 364
min: 201
max: 500
industry: Technology, Information & Media
location:
city: Boston
state: Massachusetts
country: United States
countryIso2: US
continent: North America
socialLinks:
linkedin: https://www.linkedin.com/company/lushadata
has:
- alternativeName
- alternativeDomains
- description
- companyType
- yearFounded
- subIndustry
- specialities
- sicCodes
- naicsCodes
- additionalLocations
- linkedinFollowers
- funding
- popularityTier
- logoUrl
- employeesByDepartment
- employeesByLocation
- employeesBySeniority
- competitors
- businessModel
- emails
- keywords
- socialLinks
canReveal:
- field: employeesByDepartment
credits: 1
- field: employeesByLocation
credits: 1
- field: employeesBySeniority
credits: 1
- field: competitors
credits: 1
- clientReferenceId: comp-ref-2
id: '12790225'
name: Salesforce
domain: www.salesforce.com
employeeCount:
exact: 88711
min: 100001
max: 10000000
industry: Technology, Information & Media
location:
city: San Francisco
state: California
country: United States
countryIso2: US
continent: North America
socialLinks:
linkedin: https://www.linkedin.com/company/salesforce
has:
- alternativeName
- alternativeDomains
- description
- companyType
- subIndustry
- sicCodes
- naicsCodes
- additionalLocations
- linkedinFollowers
- revenueRange
- intent
- popularityTier
- logoUrl
- employeesByDepartment
- employeesByLocation
- employeesBySeniority
- competitors
- phones
- emails
- socialLinks
canReveal:
- field: employeesByDepartment
credits: 1
- field: employeesByLocation
credits: 1
- field: employeesBySeniority
credits: 1
- field: competitors
credits: 1
- field: intent
credits: 0
billing:
creditsCharged: 1
resultsReturned: 3
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
V3ContactSearchItem:
type: object
properties:
clientReferenceId:
type: string
example: my-ref-1
id:
type: string
example: '12345'
linkedinUrl:
type: string
example: https://www.linkedin.com/in/orit-shilvock-6243bb5
email:
type: string
format: email
example: orit.shilvock@lusha.com
firstName:
type: string
example: Orit
lastName:
type: string
example: Shilvock
companyName:
type: string
example: Lusha
companyDomain:
type: string
example: lusha.com
V3Billing:
type: object
description: Credit usage summary for a V3 API request
properties:
creditsCharged:
type: integer
description: Total credits charged for this request
example: 3
resultsReturned:
type: integer
description: Number of successful results returned
example: 1
V3CompaniesSearchResponse:
type: object
properties:
requestId:
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/V3CompanyPreview'
billing:
$ref: '#/components/schemas/V3Billing'
V3CompanyPreview:
type: object
properties:
clientReferenceId:
type: string
example: comp-ref-1
id:
type: string
example: '16303253'
name:
type: string
example: Lusha
domain:
type: string
example: www.lusha.com
employeeCount:
type: object
properties:
exact:
type: integer
example: 364
min:
type: integer
example: 201
max:
type: integer
example: 500
industry:
type: string
example: Technology, Information & Media
location:
type: object
properties:
city:
type: string
example: London
state:
type: string
example: England
stateCode:
type: string
description: Free field. ISO/postal state or region code, when available.
example: MA
country:
type: string
example: United Kingdom
countryIso2:
type: string
example: GB
continent:
type: string
example: Europe
socialLinks:
type: object
properties:
linkedin:
type: string
example: https://www.linkedin.com/company/lushadata
has:
type: array
items:
type: string
description: 'Available data points that can be revealed via Enrich Companies. Includes base firmographic fields plus new revealable fields: employeesByDepartment, employeesByLocation, employeesBySeniority, competitors, businessModel, phones, emails, keywords, socialLinks, estimatedAnnualItSpend, monthlyWebsiteTraffic.
'
example:
- alternativeName
- alternativeDomains
- description
- companyType
- yearFounded
- subIndustry
- specialities
- sicCodes
- naicsCodes
- additionalLocations
- linkedinFollowers
- popularityTier
- logoUrl
- employeesByDepartment
- employeesByLocation
- employeesBySeniority
- competitors
- businessModel
- phones
- emails
- keywords
- socialLinks
- estimatedAnnualItSpend
- monthlyWebsiteTraffic
canReveal:
type: array
description: 'Data fields that can be revealed via Enrich Companies, with the credit cost per field. A cost of 0 means the field has already been revealed for this account.
'
items:
$ref: '#/components/schemas/V3CanRevealItem'
example:
- field: employeesByDepartment
credits: 1
- field: employeesByLocation
credits: 1
- field: employeesBySeniority
credits: 1
- field: competitors
credits: 1
- field: intent
credits: 0
- field: estimatedAnnualItSpend
credits: 1
- field: monthlyWebsiteTraffic
credits: 1
signalTypes:
type: array
items:
type: string
example:
- headcountIncrease3m
error:
$ref: '#/components/schemas/V3ItemError'
V3CompaniesSearchRequest:
type: object
required:
- companies
properties:
companies:
type: array
items:
$ref: '#/components/schemas/V3CompanySearchItem'
minItems: 1
maxItems: 100
options:
$ref: '#/components/schemas/V3SearchOptions'
signals:
$ref: '#/components/schemas/V3CompanySignalsDto'
V3ItemError:
type: object
description: Per-item error in a batch response
properties:
code:
type: string
enum:
- NOT_FOUND
- COMPLIANCE_RESTRICTED
- ENRICH_FAILED
- NO_SCORE
example: NOT_FOUND
message:
type: string
example: Contact not found
V3CompanySearchItem:
type: object
properties:
clientReferenceId:
type: string
example: comp-ref-1
id:
type: string
example: '16303253'
name:
type: string
example: Lusha
domain:
type: string
example: lusha.com
V3ContactPreview:
type: object
properties:
clientReferenceId:
type: string
example: my-ref-1
id:
type: string
example: '4389064704'
firstName:
type: string
example: Orit
lastName:
type: string
example: Shilvock
jobTitle:
type: object
properties:
title:
type: string
example: Vice President of Partnerships
departments:
type: array
items:
type: string
example:
- Business Development
seniority:
type: string
example: Vice President
company:
type: object
properties:
id:
type: string
example: '16303253'
name:
type: string
example: Lusha
domain:
type: string
example: www.lusha.com
location:
type: object
properties:
country:
type: string
example: Israel
state:
type: string
example: Tel Aviv District
city:
type: string
example: Tel Aviv
socialLinks:
type: object
properties:
linkedin:
type: string
example: https://www.linkedin.com/in/orit-shilvock-6243bb5
has:
type: array
items:
type: string
example:
- firstName
- lastName
- jobTitle
- location
- socialLinks
- emails
canReveal:
type: array
items:
$ref: '#/components/schemas/V3CanRevealItem'
signalTypes:
type: array
items:
type: string
example:
- promotion
- companyChange
error:
$ref: '#/components/schemas/V3ItemError'
ErrorResponse:
type: object
required:
- statusCode
- message
properties:
statusCode:
type: integer
description: HTTP status code
example: 400
message:
type: string
description: Error message
example: Validation failed
errors:
type: array
items:
type: string
description: Detailed error messages (optional, only for validation errors)
example:
- 'entityType must be one of: contact, company'
V3ContactsSearchResponse:
type: object
properties:
requestId:
type: string
format: uuid
example: 3c7f6d96-4a72-40cd-96c1-2efcfabeb727
results:
type: array
items:
$ref: '#/components/schemas/V3ContactPreview'
billing:
$ref: '#/components/schemas/V3Billing'
V3CanRevealItem:
type: object
description: Indicates a data type that can be revealed and its credit cost
properties:
field:
type: string
enum:
- emails
- phones
example: emails
credits:
type: integer
description: Credit cost (0 when already revealed for this account)
example: 1
V3SearchOptions:
type: object
description: Additional options for search requests
properties:
includePartialProfiles:
type: boolean
description: Include partial profiles in results
example: true
V3CompanySignalsDto:
type: object
required:
- types
properties:
types:
type: array
items:
type: string
enum:
- allSignals
- linkedinActivityIntent
- websiteTrafficDecrease
- websiteTrafficIncrease
- itSpendIncrease
- itSpendDecrease
- surgeInHiring
- headcountIncrease1m
- headcountIncrease3m
- headcountIncrease6m
- headcountIncrease12m
- headcountDecrease1m
- headcountDecrease3m
- headcountDecrease6m
- headcountDecrease12m
- surgeInHiringByDepartment
- surgeInHiringByLocation
- riskNews
- commercialActivityNews
- corporateStrategyNews
- financialEventsNews
- peopleNews
- marketIntelligenceNews
- productActivityNews
example:
- headcountIncrease3m
- surgeInHiring
startDate:
type: string
format: date
example: '2025-01-01'
maxResultsPerSignal:
type: integer
minimum: 1
maximum: 100
example: 10
V3ContactsSearchRequest:
type: object
required:
- contacts
properties:
contacts:
type: array
items:
$ref: '#/components/schemas/V3ContactSearchItem'
minItems: 1
maxItems: 100
options:
$ref: '#/components/schemas/V3SearchOptions'
signals:
$ref: '#/components/schemas/V3ContactSignalsDto'
V3ContactSignalsDto:
type: object
required:
- types
properties:
types:
type: array
items:
type: string
enum:
- allSignals
- promotion
- companyChange
example:
- promotion
- companyChange
startDate:
type: string
format: date
example: '2025-01-01'
maxResultsPerSignal:
type: integer
minimum: 1
maximum: 100
example: 10
responses:
BadRequest:
description: Bad request - invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: Invalid request parameters
Forbidden:
description: Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
accountInactive:
summary: Account inactive
value:
statusCode: 403
message: Your account is not active. Please reach out to support at support@lusha.com
v3NotEnabled:
summary: V3 access not enabled
value:
statusCode: 403
message: V3 API access is not enabled for your account
TooManyRequests:
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 429
message: Too many requests. Please wait before making another request.
headers:
x-rate-limit-daily:
description: Total requests allowed per day
schema:
type: integer
x-daily-requests-left:
description: Requests remaining in daily quota
schema:
type: integer
x-rate-limit-hourly:
description: Total requests allowed per hour
schema:
type: integer
x-hourly-requests-left:
description: Requests remaining in hourly quota
schema:
ty
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lusha/refs/heads/main/openapi/lusha-search-api-openapi.yml