Lusha Search & Enrich API
Resolve an identifier and return the fully revealed contact or company record in a single call, collapsing the two-phase search-then-enrich pattern where the caller has already decided to spend credits.
OpenAPI Specification
openapi: 3.2.0
info:
title: Lusha API Documentation Search & Enrich 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 & Enrich
description: '**Search & Enrich APIs:** Find and retrieve full contact or company data in a single call.
Combines Search and Enrich into one request. Provide identifiers and control what gets revealed via the `reveal` field.
> **Billing:** Two charges apply — one for the search (`api_search`) and one per revealed field.
'
x-tag-expanded: true
paths:
/v3/contacts/search-and-enrich:
post:
tags:
- Search & Enrich
summary: Search and Enrich Contacts
operationId: searchAndEnrichContacts
description: 'Find contacts and reveal their full data in a single call. Combines Search and Enrich into one request.
Provide contact identifiers the same way you would for Search Contacts. Use the `reveal` field to control what gets unlocked (`emails`, `phones`, or both).
Up to 100 contacts per request.
> **Billing:** Two charges apply — one for the search (`api_search`) and one per revealed field. The `billing.creditsCharged` in the response reflects the total.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V3ContactsSearchAndEnrichRequest'
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
reveal:
- emails
- phones
options:
includePartialProfiles: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/V3ContactsSearchAndEnrichResponse'
example:
requestId: 211ee5da-3c0d-4621-9fa5-140e393a3ced
results:
- clientReferenceId: my-ref-1
id: '4389064704'
firstName: Orit
lastName: Shilvock
fullName: Orit Shilvock
emails:
- email: orit.shilvock@lusha.com
type: work
confidence: A+
updateDate: '2026-04-23'
phones: []
tags: []
previousEmployment: []
updateDate: '2026-04-23'
billing:
creditsCharged: 2
resultsReturned: 2
'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-and-enrich:
post:
tags:
- Search & Enrich
summary: Search and Enrich Companies
operationId: searchAndEnrichCompanies
description: 'Find companies and reveal their full data in a single call. Combines Search and Enrich into one request.
Provide company identifiers the same way you would for Search Companies. Up to 100 companies per request.
> **Billing:** Same as Enrich Companies — charged per successful result via the `reveal_company` action.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V3CompaniesSearchAndEnrichRequest'
example:
companies:
- clientReferenceId: comp-ref-1
name: Lusha
- clientReferenceId: comp-ref-2
domain: salesforce.com
options:
includePartialProfiles: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/V3CompaniesSearchAndEnrichResponse'
example:
requestId: 21fe0733-65d6-436a-8d0c-2c9ac6f263f8
results:
- clientReferenceId: comp-ref-1
id: '16303253'
name: Lusha
alternativeName: lusha
domain: www.lusha.com
alternativeDomains:
- lusha.com
description: Lusha is the leader in Sales Streaming – a new sales paradigm that streams top leads straight to salespeople and handles all the outreach, so they can escape the lead grind and just sell.
companyType: Private Company
yearFounded: 2016
employeeCount:
exact: 364
min: 201
max: 500
industry: Technology, Information & Media
subIndustry: Software Development
specialities:
- data accuracy
- data enrichment
- lead discovery
- lead generation
- prospecting
- sales enablement
- sales intelligence
- software development
sicCodes:
- code: 7371
description: Custom computer programming services
naicsCodes:
- code: 541511
description: Custom Computer Programming Services
location:
city: Boston
state: Massachusetts
country: United States
countryIso2: US
continent: North America
zipCode: 02199
additionalLocations:
- city: New York City
state: New York
country: United States
countryIso2: US
continent: North America
socialLinks:
linkedin: https://www.linkedin.com/company/lushadata
linkedinFollowers: 64339
funding:
rounds:
- currency: USD
roundAmount: 205000000
roundType: Private Equity Round
roundDate: Nov 10, 2021
- currency: USD
roundAmount: 40000000
roundType: Private Equity Round
roundDate: Feb 10, 2021
totalRounds: 2
totalRoundsAmount: 245000000
currency: USD
isIpo: false
lastRoundType: Private Equity Round
lastRoundAmount: 205000000
lastRoundDate: Nov 10, 2021
technologies:
- amazon
- google analytics
popularityTier: 1
logoUrl: https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg
businessModel:
- B2B
emails:
- email: Support@Lusha.com
keywords:
- contact information
- data accuracy
- data enrichment
- lead discovery
- lead generation
- prospecting
- sales enablement
- sales intelligence
- software development
- clientReferenceId: comp-ref-2
id: '12790225'
name: Salesforce
alternativeName: salesforce
domain: www.salesforce.com
alternativeDomains:
- salesforce.com
description: 'We''re the #1 AI CRM—where humans with agents drive customer success together with AI, data, and Customer 360 apps on one platform.'
companyType: Public Company
employeeCount:
exact: 88711
min: 100001
max: 10000000
industry: Technology, Information & Media
subIndustry: Software Development
sicCodes:
- code: 7371
description: Custom computer programming services
naicsCodes:
- code: 541511
description: Custom Computer Programming Services
location:
city: San Francisco
state: California
country: United States
countryIso2: US
continent: North America
zipCode: '94105'
additionalLocations:
- country: United States
countryIso2: US
continent: North America
- city: Chicago
state: Illinois
country: United States
countryIso2: US
continent: North America
- city: London
country: United Kingdom
countryIso2: GB
continent: Europe
- city: Tel Aviv
country: Israel
countryIso2: IL
continent: Asia
socialLinks:
linkedin: https://www.linkedin.com/company/salesforce
linkedinFollowers: 6417067
revenueRange:
min: 10000000000
max: 100000000000
intent:
detectedTopics:
- topicName: Cognism Limited
metadata:
topicScore: 85
topicTrend: '+24'
topicCount: 1
technologies:
- amazon
- paypal
- google analytics
popularityTier: 1
logoUrl: https://logo.lusha.co/brightdata/year=2024/month=05/day=20/j_lwej8xik12ncr6ge4u.9e1ec373903019beff129694cb926761f065e9af.file_lwejc8mispkz3m1ng.logo_cached.jpg
phones:
- number: +1 800-420-7332
emails:
- email: datasubjectrequest@salesforce.com
billing:
creditsCharged: 3
resultsReturned: 2
'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:
V3EmailAddress:
type: object
properties:
email:
type: string
format: email
example: orit.shilvock@lusha.com
type:
type: string
enum:
- work
- private
- unknown
example: work
confidence:
type:
- string
- 'null'
example: A+
updateDate:
type: string
format: date
example: '2026-04-23'
V3SicCode:
type: object
properties:
code:
type: integer
example: 7371
description:
type: string
example: Custom computer programming services
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
V3ContactTag:
type: object
properties:
id:
type: string
name:
type: string
color:
type: string
example: '#FF5733'
V3NaicsCode:
type: object
properties:
code:
type: integer
example: 541511
description:
type: string
example: Custom Computer Programming Services
V3ContactsSearchAndEnrichRequest:
type: object
required:
- contacts
properties:
contacts:
type: array
items:
$ref: '#/components/schemas/V3ContactSearchItem'
minItems: 1
maxItems: 100
reveal:
type: array
items:
type: string
enum:
- emails
- phones
example:
- emails
- phones
options:
$ref: '#/components/schemas/V3SearchOptions'
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
V3ContactsSearchAndEnrichResponse:
type: object
properties:
requestId:
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/V3SearchAndEnrichContactResult'
billing:
$ref: '#/components/schemas/V3Billing'
V3SearchAndEnrichContactResult:
allOf:
- $ref: '#/components/schemas/V3EnrichedContact'
- type: object
properties:
clientReferenceId:
type: string
example: my-ref-1
V3EnrichedContactCompanyRef:
type: object
properties:
id:
type: string
example: '16303253'
name:
type: string
example: Lusha
domain:
type: string
example: www.lusha.com
industry:
type: string
example: Technology, Information & Media
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
V3CompaniesSearchAndEnrichResponse:
type: object
properties:
requestId:
type: string
format: uuid
results:
type: array
items:
$ref: '#/components/schemas/V3SearchAndEnrichCompanyResult'
billing:
$ref: '#/components/schemas/V3Billing'
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
V3EnrichedCompany:
type: object
properties:
id:
type: string
example: '16303253'
name:
type: string
example: Lusha
alternativeName:
type: string
example: lusha
domain:
type: string
example: www.lusha.com
alternativeDomains:
type: array
items:
type: string
example:
- lusha.com
description:
type: string
example: Lusha is the leader in Sales Streaming.
companyType:
type: string
example: Private Company
yearFounded:
type: number
example: 2016
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
subIndustry:
type: string
example: Software Development
specialities:
type: array
items:
type: string
example:
- data enrichment
- sales intelligence
industryTags:
type: array
items:
type: string
example:
- saas
- b2b
sicCodes:
type: array
items:
$ref: '#/components/schemas/V3SicCode'
naicsCodes:
type: array
items:
$ref: '#/components/schemas/V3NaicsCode'
companyOffering:
type: string
description: Free field. Short description of what the company sells or does.
example: Cloud-based CRM software for small businesses
emailDomain:
type: string
description: Free field. Primary domain used for company email addresses.
example: lusha.com
additionalIndustries:
type: array
description: Free field. Up to 2 secondary industry classifications beyond the primary `industry`/`subIndustry`.
maxItems: 2
items:
type: object
properties:
industry:
type: string
example: Financial Services
subIndustry:
type: string
example: Insurance
estimatedAnnualItSpend:
type:
- object
- 'null'
description: 'Revealed via reveal: ["estimatedAnnualItSpend"] in Enrich Companies. Charged 1 credit when non-null.'
properties:
value:
type: number
example: 500000
currency:
type: string
example: USD
valueUsd:
type: number
example: 500000
monthlyWebsiteTraffic:
type:
- object
- 'null'
description: 'Revealed via reveal: ["monthlyWebsiteTraffic"] in Enrich Companies. Charged 1 credit when non-null.'
properties:
visits:
type: number
example: 128450
momChangePercent:
type: number
example: 4.3
month:
type: string
example: 2026-06
location:
$ref: '#/components/schemas/V3CompanyLocation'
additionalLocations:
type: array
items:
$ref: '#/components/schemas/V3CompanyLocation'
socialLinks:
type: object
properties:
linkedin:
type: string
example: https://www.linkedin.com/company/lushadata
facebook:
type:
- string
- 'null'
description: 'Company Facebook page URL. Included automatically when available - no `reveal` entry needed. Omitted from the response when not available (never returned empty). Free field - no credits charged. Available on all plans.
'
example: https://www.facebook.com/lusha
x:
type:
- string
- 'null'
description: 'Company X (formerly Twitter) profile URL. Included automatically when available - no `reveal` entry needed. Omitted from the response when not available (never returned empty). Free field - no credits charged. Available on all plans.
'
example: https://x.com/lusha
linkedinFollowers:
type: number
example: 64339
revenueRange:
type: object
properties:
min:
type: number
example: 10000000
max:
type: number
example: 50000000
funding:
description: Funding payload when present
intent:
description: Intent payload when present
technologies:
type: array
items:
type: string
example:
- react
- node.js
- aws
popularityTier:
type: number
example: 1
logoUrl:
type: string
example: https://logo.lusha.co/logo.jpg
employeesByDepartment:
type: array
description: 'Breakdown of employees by department. Revealed via `reveal: ["employeesByDepartment"]` in Enrich Companies.
'
items:
type: object
properties:
department:
type: string
description: Department name
example: Engineering & Technical
count:
type: integer
description: Number of employees in this department
example: 14
example:
- department: Engineering & Technical
count: 14
- department: Operations
count: 40
- department: Other
count: 104
employeesByLocation:
type: array
description: 'Breakdown of employees by country and state. Revealed via `reveal: ["employeesByLocation"]` in Enrich Companies.
'
items:
type: object
properties:
country:
type: string
description: Country name
example: United States
state:
type:
- string
- 'null'
description: State or region (null when not available)
example: Colorado
count:
type: integer
description: Number of employees in this location
example: 54
example:
- country: United States
state: Colorado
count: 54
- country: United States
state: Texas
count: 44
- country: United States
state: null
count: 162
employeesBySeniority:
type: array
description: 'Breakdown of employees by seniority level. Revealed via `reveal: ["employeesBySeniority"]` in Enrich Companies.
'
items:
type: object
properties:
seniority:
type: string
description: Seniority level
example: Manager
count:
type: integer
description: Number of employees at this seniority level
example: 39
example:
- seniority: Non-Manager
count: 122
- seniority: Manager
count: 39
- seniority: Vice President
count: 3
competitors:
type: array
description: 'List of competitor companies. Revealed via `reveal: ["competitors"]` in Enrich Companies. Use Enrich Companies with the returned IDs to get full firmographic data on each competitor.
'
items:
type: object
properties:
id:
type: string
description: Lusha company ID of the competitor
example: '2497917'
name:
type: string
description: Company name of the competitor
example: Clearbit
domain:
type: string
description: Primary domain of the competitor
example: clearbit.com
example:
- id: '2497917'
name: Clearbit
domain: clearbit.com
- id: '9781263'
name: Hunter.io
domain: hunter.io
- id: '40857684'
name: MCJ Solutions Inc
domain: zoominfo.com
businessModel:
type: array
description: Company business model classification (e.g. B2B, B2C)
items:
type: string
example:
- B2B
phone:
type: string
description: Company phone number
example: (480) 729-6394
email:
type: string
description: Company contact email address
example: info@cobbmechanical.com
keywords:
type: array
description: Keywords associated with the company (normalized from specialities and description)
items:
type: string
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lusha/refs/heads/main/openapi/lusha-search-enrich-api-openapi.yml