> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search and Enrich Companies
> Find up to 100 companies by identifier and reveal their full firmographic data in a single call.
Use this endpoint to find companies and reveal their full data in one request - it combines [Search Companies](/api-reference/search/search-companies) and [Enrich Companies](/api-reference/enrich/enrich-companies) into a single call. Provide identifiers the same way you would for Search Companies.
If you need to inspect what's revealable and its credit cost before committing to a reveal, call [Search Companies](/api-reference/search/search-companies) first, then [Enrich Companies](/api-reference/enrich/enrich-companies) separately. Use this combined endpoint when you already know you want the full profile.
## Endpoint
```
POST https://api.lusha.com/v3/companies/search-and-enrich
```
## Authentication
Your Lusha API key.
## Accepted identifiers
Each company in the `companies` array needs **at least one** of the following:
* Lusha company `id`
* `name`
* `domain`
## Request body
Up to 100 companies to find and enrich.
Your own reference ID for this company. Echoed back on the matching result.
Example: `comp-ref-1`
A Lusha company ID.
The company name.
The company domain.
When `true`, includes companies with incomplete data in the results instead of dropping them.
Unlike Search and Enrich Contacts, this endpoint doesn't take a `reveal` field - every matched company returns full firmographics automatically.
## Response
Unique ID for this request, in UUID format.
One entry per company you searched for. Each result has the same shape as an [Enrich Companies](/api-reference/enrich/enrich-companies) result, plus `clientReferenceId`.
Echoes the `clientReferenceId` you sent for this company.
`exact`, `min`, and `max` headcount.
HQ location.
All other known company sites.
LinkedIn URL.
`min` and `max` revenue estimates.
Funding history, when available.
Present instead of profile data when the lookup or enrich fails for this company.
One of `NOT_FOUND`, `COMPLIANCE_RESTRICTED`, `ENRICH_FAILED`.
Human-readable description.
Credits charged for this request.
Number of successful results.
**Billing:** Same as Enrich Companies - charged per successful result via the `reveal_company` action.
## Error codes
| Status | Meaning |
| ------ | ----------------------------------------------------- |
| `400` | Bad request - invalid input data |
| `401` | Unauthorized - invalid or missing API key |
| `402` | Payment required - insufficient credits |
| `403` | Forbidden - account inactive or V3 access not enabled |
| `429` | Too many requests - rate limit exceeded |
## Example
```bash cURL theme={null}
curl --request POST \
--url https://api.lusha.com/v3/companies/search-and-enrich \
--header 'api_key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"companies": [
{ "clientReferenceId": "comp-ref-1", "name": "Lusha" },
{ "clientReferenceId": "comp-ref-2", "domain": "salesforce.com" }
],
"options": {
"includePartialProfiles": true
}
}'
```
```json Request body theme={null}
{
"companies": [
{ "clientReferenceId": "comp-ref-1", "name": "Lusha" },
{ "clientReferenceId": "comp-ref-2", "domain": "salesforce.com" }
],
"options": {
"includePartialProfiles": true
}
}
```
```json Example response theme={null}
{
"requestId": "6e4b1192-9440-42c4-9a3e-793ddef6d73c",
"results": [
{
"clientReferenceId": "comp-ref-1",
"id": "16303253",
"name": "Lusha",
"domain": "www.lusha.com",
"description": "Lusha is the leader in Sales Streaming.",
"companyType": "Private Company",
"yearFounded": 2016,
"employeeCount": { "exact": 364, "min": 201, "max": 500 },
"industry": "Technology, Information & Media",
"subIndustry": "Software Development"
}
],
"billing": {
"creditsCharged": 1,
"resultsReturned": 1
}
}
```
## OpenAPI
````yaml post /v3/companies/search-and-enrich
openapi: 3.0.3
info:
title: Lusha API Documentation
version: 0.0.1
x-logo:
url: https://www.lusha.com/logo.png
license:
name: Proprietary
url: https://lusha.com/legal/terms
description: >
**This is the Lusha API V3 documentation.**
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/`.
For more information on V3, refer to the [Migration Guide](/tutorials/v3-migration-guide).
---
Lusha 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.
Use the Lusha API to **search for new prospects**, **enrich existing
records**, **react to real-world changes**, and **expand coverage** with
AI-powered lookalike recommendations.
> All API requests must be made over **HTTPS**. All responses are returned
in **JSON** format.
---
## Available Endpoints
| Category | Description |
|---|---|
| [**Search**](#tag/Search) | Find contacts or companies using known
identifiers |
| [**Enrich**](#tag/Enrich) | Retrieve full profile data for contacts or
companies by ID |
| [**Search & Enrich**](#tag/Search-and-Enrich) | Find and retrieve full
contact or company data in a single call |
| [**Prospecting**](#tag/Prospecting) | Filter-based search across contacts
and companies |
| [**Lookalikes**](#tag/Lookalikes) | AI-powered recommendations for similar
contacts and companies |
| [**Buying Group**](#tag/Buying-Group) | Identify decision makers,
champions, and end users within target accounts |
| [**Contacts Tables**](#tag/Contacts-Tables) | Persist, organize, and
enrich contacts in reusable tables |
| [**Companies Tables**](#tag/Companies-Tables) | Persist, organize, and
enrich companies in reusable tables |
| [**Signals**](#tag/Signals) | Real-world activity data for contacts and
companies |
| [**Website Visitors**](#tag/Website-Visits) | Companies ranked by
website-visit signals for your tracked domains |
| [**Conversations**](#tag/Conversations) | Search recorded sales
conversations and fetch their transcripts |
| [**Filters**](#tag/Filters) | Discover valid filter values for prospecting
|
| [**Webhooks**](#tag/Webhooks) | Real-time signal notifications via HTTP
callbacks |
| [**Account**](#tag/Account) | Usage, credits, rate limits, and pricing |
**Waterfall Reveal for Contact Enrichment.**
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).
---
## Data Source and Privacy
**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.
For more details on how we collect and handle data, see our [Privacy
Policy](https://lusha.com/legal/privacy-notice/).
---
## Legal Notices
(a) Data brokers and other third-party platforms may not embed, expose, or
otherwise provide access to the Lusha API, or to Data obtained through it,
on or through their own website, product, or service, without Lusha's prior
written consent.
(b) Data obtained through the API may not be used to train or develop AI/ML
systems, subject to the terms and exceptions outlined in the [Terms and
Conditions](https://lusha.com/legal/terms).
---
## Authentication
All 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.
> Generate and manage your API key in the [Lusha
dashboard](https://dashboard.lusha.com/enrich/api).
Store your API key securely and use it only in **server-side environments**.
---
## Rate Limiting
Lusha 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.
Rate limits for the **Credit Usage API** differ from standard endpoint
limits.
> **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.
**Rate Limit Response Headers**
| Header | Description |
|--------|-------------|
| `x-rate-limit-daily` | Total requests allowed per day |
| `x-daily-requests-left` | Requests remaining in your daily quota |
| `x-daily-usage` | Requests made in the current daily period |
| `x-rate-limit-hourly` | Total requests allowed per hour |
| `x-hourly-requests-left` | Requests remaining in your hourly quota |
| `x-hourly-usage` | Requests made in the current hourly period |
| `x-rate-limit-minute` | Total requests allowed per minute |
| `x-minute-requests-left` | Requests remaining in the current minute window
|
| `x-minute-usage` | Requests made in the current minute window |
---
## Error Codes
Lusha uses standard HTTP status codes to indicate the result of each
request.
| Code | Name | Description |
|------|------|-------------|
| `200` | OK | Request was successful |
| `400` | Bad Request | Request is malformed or missing required fields |
| `401` | Unauthorized | API key is missing or invalid |
| `402` | Payment Required | Insufficient credits or payment needed |
| `403` | Forbidden | Account is inactive. Contact support@lusha.com |
| `404` | Not Found | Endpoint or resource does not exist |
| `429` | Too Many Requests | Rate limit or daily quota exceeded |
| `451` | Unavailable For Legal Reasons | Request blocked due to GDPR
regulations |
| `499` | Client Closed Request | Request timed out before completing |
| `5XX` | Server Error | Issue on Lusha's end. Retry with exponential
backoff |
**Error Response Format**
```json
{
"statusCode": 400,
"message": "Invalid request parameters"
}
```
**Tables-specific error codes**
| Code | Status | Meaning |
|---|---|---|
| `TABLE_NOT_FOUND` | 404 | The `table_id` does not exist or is not
accessible to this account |
| `COLUMN_NOT_FOUND` | 404 | The `column_id` does not exist on the given
table |
| `TABLE_NAME_CONFLICT` | 409 | A table with this name already exists |
Tables error bodies use the shape `{ "message": "...", "code": , ...
}` rather than the `statusCode`/`errors` shape used elsewhere in this doc.
**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.
**Tips for Handling Errors**
- Verify your API key is correct and active
- Read the `message` field for specific troubleshooting details
- For `429` errors, wait before retrying
- For `5XX` errors, use exponential backoff before retrying
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
- name: Enrich
description: >
**Enrich APIs:** Retrieve full profile data for contacts or companies by
ID.
Pass IDs from Search results to reveal emails, phones, and full
firmographic data.
> **Billing:** Charged per revealed field via per-datapoint pricing
(`revealEmail`, `revealPhone`, `reveal_company`).
x-tag-expanded: true
- 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. Premium data points are
never returned unless you request them explicitly in `reveal`.
> **Billing:** Two charges apply - one for the search (`api_search`) and
one per revealed field.
x-tag-expanded: true
- name: Prospecting
description: >
**Prospecting APIs:** Filter-based search for contacts and companies.
Use prospecting to find new records that match your Ideal Customer Profile
(ICP). Apply rich filters across:
- **Contact attributes:** title, seniority, location, signals
- **Company attributes:** size, revenue, industry, technologies, intent
Pass `tableId` to also persist matching results into an existing table.
See [Contacts Tables](#tag/Contacts-Tables) or [Companies
Tables](#tag/Companies-Tables).
> **Billing:** Uses the capture/charge model with `api_search` actions.
Signal charges apply additionally.
x-tag-expanded: true
- name: Lookalikes
description: >
**Lookalike APIs:** Use AI-powered recommendations to discover contacts
and companies similar to your best existing customers. The Contact
Lookalikes and Company Lookalikes endpoints return paginated results you
can pipe directly into Enrich for full data.
Pass `tableId` to also persist matching results into an existing table.
See [Contacts Tables](#tag/Contacts-Tables) or [Companies
Tables](#tag/Companies-Tables).
x-tag-expanded: true
- name: Buying Group
description: >
**Buying Group API:** Identify and prioritize the buying committee within
a set of target companies.
Supply up to 25 companies by `domain` or Lusha company `id`. The model
scores and labels each returned contact with a persona role -
`decision_maker`, `potential_champion`, or `end_user` - so you can
prioritize outreach across the buying committee instead of working one
contact at a time.
Results are lightweight previews grouped by company. Use [Enrich
Contacts](#operation/enrichContacts) with the returned `id` to reveal
emails and phones.
> **Billing:** Charged per contact returned via the `buyingGroupContact`
action.
x-tag-expanded: true
- name: Contacts Tables
description: >
**Contacts Tables API:** Create and manage persistent tables of contacts
inside Lusha.
Tables are spreadsheets with configurable columns - default Lusha fields,
enrichment data, Signals, AI insights, premium data points, CRM fields,
and custom fields. Populate a table directly through the endpoints below,
or pass `tableId` on Prospecting, Enrich, Signals, or Lookalike calls to
persist those results automatically.
Every surface that touches table data - this API, MCP, and the Workspace
UI - reads and writes the same underlying data. Changes made through one
surface are reflected on the others.
**Working with tables:**
- **Tables** - create, list, get status, update
(rename/archive/visibility), delete
- **Entities** - add, remove, or read the rows in a table
- **Columns** - browse the Lusha column catalog, add columns, list,
remove, or run a column across a table's rows
**Owner resolution:** `owner.email` resolves to a user on your account and
determines table ownership. **Required on every call when authenticating
with an API key** - omitting it returns `400`. Optional for OAuth/token
callers, since the caller is already identified by the token. Sent in the
body as `owner: { email }` on `POST`/`PATCH` calls (and on `DELETE
.../entities`, which carries a body); sent as a `?email=` query parameter
on other `GET`/`DELETE` calls, which have no body.
**Billing:**
- Adding contacts to a table is free.
- Reading entities (`GET .../entities`) charges per row returned.
- Create / List / Get / Update / Delete / Column Catalog / Add Columns /
List Columns / Remove Column / Remove Entities are free. (Add Columns is
free today - credits aren't charged for it yet.)
- Running a column charges per row per the column's tier (contact
enrichment per row with data; signal/AI/score per row per run).
- Non-public-API-plan accounts always resolve to `0` credits charged.
**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities
per table · max 500 tables per account.
See also: [Companies Tables](#tag/Companies-Tables).
x-tag-expanded: true
- name: Companies Tables
description: >
**Companies Tables API:** Create and manage persistent tables of companies
inside Lusha.
Tables are spreadsheets with configurable columns - default Lusha fields,
enrichment data, Signals, AI insights, premium data points, CRM fields,
and custom fields. Populate a table directly through the endpoints below,
or pass `tableId` on Prospecting, Enrich, Signals, or Lookalike calls to
persist those results automatically.
Every surface that touches table data - this API, MCP, and the Workspace
UI - reads and writes the same underlying data. Changes made through one
surface are reflected on the others.
**Working with tables:**
- **Tables** - create, list, get status, update
(rename/archive/visibility), delete
- **Entities** - add, remove, or read the rows in a table
- **Columns** - browse the Lusha column catalog, add columns, list,
remove, or run a column across a table's rows
**Owner resolution:** `owner.email` resolves to a user on your account and
determines table ownership. **Required on every call when authenticating
with an API key** - omitting it returns `400`. Optional for OAuth/token
callers, since the caller is already identified by the token. Sent in the
body as `owner: { email }` on `POST`/`PATCH` calls (and on `DELETE
.../entities`, which carries a body); sent as a `?email=` query parameter
on other `GET`/`DELETE` calls, which have no body.
**Billing:**
- Adding companies to a table charges `reveal_company` per **newly added**
company, deduped so duplicates and already-present companies aren't
charged again.
- Reading entities (`GET .../entities`) charges per row returned.
- Create / List / Get / Update / Delete / Column Catalog / Add Columns /
List Columns / Remove Column / Remove Entities are free. (Add Columns is
free today - credits aren't charged for it yet.)
- Running a column charges per row per the column's tier (company
enrichment once per company per table - re-runs on an already-paid company
are free; signal/AI/score per row per run).
- Non-public-API-plan accounts always resolve to `0` credits charged.
**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities
per table · max 500 tables per account.
See also: [Contacts Tables](#tag/Contacts-Tables).
x-tag-expanded: true
- name: Signals
description: >
Real-world activity data for contacts and companies.
Signals are available as standalone endpoints or as an optional `signals`
filter on Search and Prospecting endpoints.
**Contact signal types:** `promotion`, `companyChange`, `allSignals`
----
**Company signal types:** `headcountIncrease1m/3m/6m/12m`,
`headcountDecrease1m/3m/6m/12m`, `surgeInHiring`,
`surgeInHiringByDepartment`, `surgeInHiringByLocation`,
`websiteTrafficIncrease`, `websiteTrafficDecrease`, `itSpendIncrease`,
`itSpendDecrease`, `riskNews`, `commercialActivityNews`,
`corporateStrategyNews`, `financialEventsNews`, `peopleNews`,
`marketIntelligenceNews`, `productActivityNews`, `allSignals`
----
**Signal Score:** Use [Score Companies by Signal
Activity](#operation/getCompanySignalScores) or [Score Contacts by Signal
Activity](#operation/getContactSignalScores) to get a single aggregate
momentum score ([0,1]) plus the active signal breakdown for a batch of
entities, rather than a raw event list.
----
Credits are charged per matched signal per result via `showSignalsContact`
or `showSignalsCompany`.
Pass `tableId` to also persist matching results into an existing table.
See [Contacts Tables](#tag/Contacts-Tables) or [Companies
Tables](#tag/Companies-Tables).
x-tag-expanded: true
- name: Website Visits
description: >
Retrieve companies ranked by website-visit signals for your tracked
domains.
Domains must be configured for tracking in the dashboard. Each result combines a V3 company firmographic preview with behavioral visit metrics (score, sessions, unique visitors, avg session length, and more).
x-tag-expanded: true
- name: Conversations
description: >
**Conversations API:** Search the sales conversations recorded by Lusha
Conversations for your account, and fetch speaker-attributed transcripts.
Search Conversations returns each conversation's metadata, AI summary,
action items, risks, objections, competitor mentions, coaching analysis,
and chapters - transcripts are not included. Fetch the transcript for a
single conversation separately.
**Two search modes on one contract:**
- **Keyword mode** - supply `query` to rank conversations by transcript
content. All other filters are ignored.
- **Filter mode** - omit `query` and supply the structural filters (dates,
contact names, company domains, meeting titles).
Only conversations belonging to your account whose post-call processing
has completed are returned. `summary`, `coaching`, and `chapters` come
from an asynchronous pipeline and are `null`/empty until it has run - a
`null` summary means "analysis not ready yet", not "nothing found".
> **Billing:** Search charges 1 credit per block of up to 25 conversations
returned (via `ci_meeting_data_export`); a request that returns nothing is
free. Transcript charges 1 credit per successful request (via
`ci_transcript_analysis`); a `404` is never charged. While the relevant
action isn't yet seeded on your account's pricebook, the endpoint stays
free (`billing.creditsCharged` is `0`).
x-tag-expanded: true
- name: Filters
description: >
**Filter APIs:** Retrieve available filter values for prospecting.
Use the discovery endpoints to list all available filter types, then fetch
valid values for a specific filter type before building a prospecting
request.
**Contact filter types:** `departments`, `seniority`,
`existingDataPoints`, `countries`, `locations`
**Company filter types:** `names`, `sizes`, `revenues`, `locations`,
`sics`, `naics`, `industriesLabels`, `intentTopics`, `technologies`
x-tag-expanded: true
- name: Webhooks
description: >
Subscribe to real-time notifications when contacts change jobs or
companies experience key business events.
Webhooks deliver HTTP POST requests to your endpoints when signals occur -
from promotions and job changes to company growth.
> For a full list of available signals, refer to [**Signal
Options**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions).
---
**Key Features:**
- Real-time contact & company signal notifications
- Bulk subscription management (up to 25 items per request)
- Secure delivery with HMAC-SHA256 signatures
- Delivery monitoring with audit logs
**Available Endpoints:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/subscriptions` | Create subscriptions (bulk supported) |
| GET | `/api/subscriptions` | List all subscriptions |
| GET | `/api/subscriptions/{id}` | Get subscription by ID |
| PATCH | `/api/subscriptions/{id}` | Update subscription |
| POST | `/api/subscriptions/delete` | Delete subscriptions (bulk
supported) |
| POST | `/api/subscriptions/{id}/test` | Test subscription delivery |
| GET | `/api/audit-logs` | Get webhook delivery logs |
| GET | `/api/audit-logs/stats` | Get delivery statistics |
| GET | `/api/account/secret` | Get account webhook secret |
| POST | `/api/account/secret/regenerate` | Regenerate account secret |
| POST | `/api/subscriptions/opt-out` | Subscribe to contact opt-out
notifications |
> **Webhook Delivery Acknowledgment:** When receiving webhook deliveries
(POST requests), your endpoint must acknowledge with a specific response
format. See the [Create Subscription](#operation/createSubscription)
endpoint for the required acknowledgment structure.
---
Rate Limits
| Operation | Limit |
|-----------|-------|
| API Requests | 100 requests/minute per account |
| Create Subscriptions | 25 items per request |
| Delete Subscriptions | 25 items per request |
---
Security & Verification
**HTTPS Requirement:**
- Production webhook URLs **must** use HTTPS
- HTTP URLs are not accepted
**Signature Verification:**
All webhook deliveries include an `X-Lusha-Signature` header containing an
HMAC-SHA256 signature. Verify this signature to ensure the request is from
Lusha:
1. Extract the `X-Lusha-Signature` and `X-Lusha-Timestamp` headers
2. Concatenate: `timestamp + "." + JSON.stringify(payload)`
3. Compute HMAC-SHA256 using your webhook secret
4. Compare the computed signature with the received signature
**Example (Node.js):**
```javascript
const crypto = require('crypto');
function verifySignature(payload, signature, timestamp, secret) {
const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
```
> **Security Best Practice:** Always verify webhook signatures to prevent
spoofed requests.
---
Credits & Billing
**Credit Charges:**
- Credits are charged when signals are detected and delivered to your
webhook
- The `creditsCharged` field in the webhook payload indicates how many
credits were used
- Credits are deducted from your account balance per signal type
**No Duplicate Charges:**
- Each signal is delivered once and charged once
- Webhook delivery retries do not incur additional charges
---
Error Response Format
All error responses follow this format:
```json
{
"statusCode": 400,
"message": "Validation failed",
"errors": ["entityType must be one of: contact, company"]
}
```
| Field | Type | Description |
|-------|------|-------------|
| `statusCode` | number | HTTP status code |
| `message` | string | Error message |
| `errors` | string[] | Detailed error messages (optional) |
---
x-tag-expanded: true
- name: Account
description: >
**Account API:** Retrieve account usage, credit balance, rate limits, plan
details, and pricing.
Use this endpoint to monitor consumption and understand the credit cost of
each action type in the public API flow.
> **Rate limit:** 5 requests per minute.
x-tag-expanded: true
paths:
/v3/companies/search-and-enrich:
post:
tags:
- Search & Enrich
summary: Search and Enrich Companies
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.
Use the `reveal` field to control which premium data points are
unlocked, exactly as you would on Enrich Companies. Premium fields -
including `directParent` and `ultimateParent` - are returned only when
you name them in `reveal`; they are never included by default.
> **Billing:** Same as Enrich Companies - charged per successful result
via the `reveal_company` action, plus one charge per revealed field.
operationId: searchAndEnrichCompanies
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
- clientReferenceId: comp-ref-3
domain: 4d.com
reveal:
- directParent
- ultimateParent
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
directParent: null
ultimateParent: null
- clientReferenceId: comp-ref-3
id: '18654301'
name: 4D
domain: 4d.com
companyType: Subsidiary
directParent:
lushaCompanyId: v1.XyZw...
name: Volaris Group
domain: volarisgroup.com
ultimateParent:
lushaCompanyId: v1.QrSt...
name: Constellation Software Inc.
domain: csisoftware.com
hqCountry: Canada
billing:
creditsCharged: 5
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:
V3CompaniesSearchAndEnrichRequest:
type: object
required:
- companies
properties:
companies:
type: array
items:
$ref: '#/components/schemas/V3CompanySearchItem'
minItems: 1
maxItems: 100
reveal:
type: array
items:
type: string
enum:
- employeesByDepartment
- employeesByLocation
- employeesBySeniority
- competitors
- intent
- estimatedAnnualItSpend
- monthlyWebsiteTraffic
- openJobsTotal
- openJobsByDepartment
- openJobsByLocation
- openJobsBySeniority
- directParent
- ultimateParent
description: >
Additional data fields to reveal, using the same tokens as Enrich
Companies.
Each field is charged separately per result. Premium fields are
returned only
when named here - omitting `reveal` returns base firmographics
alone.
See [Enrich Companies](#operation/enrichCompanies) for what each
token unlocks.
example:
- directParent
- ultimateParent
options:
$ref: '#/components/schemas/V3SearchOptions'
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
V3SearchOptions:
type: object
description: Additional options for search requests
properties:
includePartialProfiles:
type: boolean
description: Include partial profiles in results
example: true
V3SearchAndEnrichCompanyResult:
allOf:
- $ref: '#/components/schemas/V3EnrichedCompany'
- type: object
properties:
clientReferenceId:
type: string
example: comp-ref-1
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
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'
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
description: >-
Revealed via reveal: ["estimatedAnnualItSpend"] in Enrich Companies.
Charged 1 credit when non-null.
nullable: true
properties:
value:
type: number
example: 500000
currency:
type: string
example: USD
valueUsd:
type: number
example: 500000
monthlyWebsiteTraffic:
type: object
description: >-
Revealed via reveal: ["monthlyWebsiteTraffic"] in Enrich Companies.
Charged 1 credit when non-null.
nullable: true
properties:
visits:
type: number
example: 128450
momChangePercent:
type: number
example: 4.3
month:
type: string
example: 2026-06
openJobs:
$ref: '#/components/schemas/V3OpenJobs'
directParent:
type: object
allOf:
- $ref: '#/components/schemas/V3CompanyParent'
description: >-
The company's immediate parent in its ownership tree. Revealed via
reveal: ["directParent"] on Enrich Companies and Search & Enrich
Companies - it is not returned unless requested. Charged 1 credit
when non-null. `null` when the company has no known parent (for
example, it is independent or is itself the ultimate parent).
nullable: true
ultimateParent:
type: object
allOf:
- $ref: '#/components/schemas/V3CompanyParent'
description: >-
The company at the top of its ownership tree. Revealed via reveal:
["ultimateParent"] on Enrich Companies and Search & Enrich Companies
- it is not returned unless requested. Charged 1 credit when
non-null. For a company with a single level of ownership, this
matches `directParent`. `null` when the company has no known parent.
nullable: true
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
nullable: true
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
nullable: true
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
instagram:
type: array
items:
type: string
description: >
Company Instagram profile URLs. Included automatically when
Lusha holds the data - no `reveal` entry needed, no credit cost.
Returned as a list because a company can hold more than one
profile on this network; every value Lusha holds is returned.
Omitted from the response entirely when no data is available
(never returned as `null` or an empty list). Company-level data,
contains no personal information, refreshed monthly. Available
on all plans.
example:
- https://www.instagram.com/acmecorp
youtube:
type: array
items:
type: string
description: >
Company YouTube channel URLs. Included automatically when Lusha
holds the data - no `reveal` entry needed, no credit cost.
Returned as a list because a company can hold more than one
channel on this network (multiple YouTube channels are common);
every value Lusha holds is returned. Omitted from the response
entirely when no data is available (never returned as `null` or
an empty list). Company-level data, contains no personal
information, refreshed monthly. Available on all plans.
example:
- https://www.youtube.com/c/acmecorp
- https://www.youtube.com/channel/UCY23V0it8LSbQhB91Esxrbg
tiktok:
type: array
items:
type: string
description: >
Company TikTok profile URLs. Included automatically when Lusha
holds the data - no `reveal` entry needed, no credit cost.
Returned as a list because a company can hold more than one
profile on this network; every value Lusha holds is returned.
Omitted from the response entirely when no data is available
(never returned as `null` or an empty list). Company-level data,
contains no personal information, refreshed monthly. Available
on all plans.
example:
- https://www.tiktok.com/@acmecorp
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
nullable: true
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
example:
- construction
- hvac
- plumbing
- mechanical system
specialitiesRefactored:
type: array
description: Normalized version of the specialities list
items:
type: string
example:
- construction
- hvac
- industrial piping
- mechanical systems
- plumbing
error:
$ref: '#/components/schemas/V3ItemError'
V3SicCode:
type: object
properties:
code:
type: integer
example: 7371
description:
type: string
example: Custom computer programming services
V3NaicsCode:
type: object
properties:
code:
type: integer
example: 541511
description:
type: string
example: Custom Computer Programming Services
V3OpenJobs:
type: object
description: >
Open job posting counts. Each sub-field is revealed independently in
Enrich Companies via `reveal: ["openJobsTotal", "openJobsByDepartment",
"openJobsByLocation", "openJobsBySeniority"]`. A sub-field is present
only when its matching token was requested in `reveal` and data exists
for it; sub-fields that weren't requested, or that have no data, are
omitted. Department, location, and seniority values use the same
vocabularies as the existing prospecting filters.
nullable: true
properties:
total:
type: integer
description: Total number of open job postings. Revealed via `openJobsTotal`.
example: 47
byDepartment:
type: array
description: >-
Open job counts broken down by department. Revealed via
`openJobsByDepartment`.
items:
$ref: '#/components/schemas/V3OpenJobsByDepartment'
byLocation:
type: array
description: >-
Open job counts broken down by location. Revealed via
`openJobsByLocation`.
items:
$ref: '#/components/schemas/V3OpenJobsByLocation'
bySeniority:
type: array
description: >-
Open job counts broken down by seniority level. Revealed via
`openJobsBySeniority`.
items:
$ref: '#/components/schemas/V3OpenJobsBySeniority'
V3CompanyParent:
type: object
description: >-
A company in an ownership tree, returned by the `directParent` and
`ultimateParent` premium reveal fields. Pass `lushaCompanyId` back to
Enrich Companies to retrieve the parent's full firmographic profile.
properties:
lushaCompanyId:
type: string
description: >-
Lusha company ID of the parent. Use this with Enrich Companies to
look up the parent.
example: v1.QrSt...
name:
type: string
example: Constellation Software Inc.
domain:
type: string
example: csisoftware.com
hqCountry:
type: string
description: Country of the parent's headquarters. Not always present.
example: Canada
V3CompanyLocation:
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
zipCode:
type: string
description: Postal/ZIP code (present on HQ location when available)
example: '80904'
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
V3OpenJobsByDepartment:
type: object
description: Open job posting count for a single department.
properties:
department:
type: string
example: Engineering
count:
type: integer
example: 21
V3OpenJobsByLocation:
type: object
description: Open job posting count for a single location.
properties:
location:
type: string
example: United States
count:
type: integer
example: 12
V3OpenJobsBySeniority:
type: object
description: Open job posting count for a single seniority level.
properties:
seniority:
type: string
example: Manager
count:
type: integer
example: 5
responses:
BadRequest:
description: Bad request - invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: Invalid request parameters
Unauthorized:
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 401
message: Invalid API key
PaymentRequired:
description: Payment required - insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 402
message: Insufficient credits for this operation
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:
type: integer
x-rate-limit-minute:
description: Total requests allowed per minute
schema:
type: integer
x-minute-requests-left:
description: Requests remaining in current minute window
schema:
type: integer
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: >
Your Lusha API key. You can find this in your Lusha dashboard under API
settings.
Include this key in the `api_key` header for all requests.
````