> ## 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.
# POST /prospecting/contact/search - Search contacts
> Search Lusha's contact database using ICP filters like job title, seniority, location, and department. Step 2 of the prospecting flow.
Use this endpoint to query Lusha's contact database with filters aligned to your Ideal Customer Profile. You get back a list of matching contacts with IDs you then pass to the [Enrich Contacts](/v2/api-reference/prospecting/enrich-contacts) endpoint to retrieve full details. This is **step 2** of the three-step prospecting flow.
**Prospecting flow**
| Step | Endpoint | Purpose |
| ---- | ------------------------------------ | -------------------------------------------- |
| 1 | Filters API | Discover valid filter values for your search |
| 2 | **POST /prospecting/contact/search** | Query contacts using your filters |
| 3 | POST /prospecting/contact/enrich | Retrieve full contact details by ID |
## Endpoint
```
POST https://api.lusha.com/prospecting/contact/search
```
**Authentication:** API key (`ApiKeyAuth`)
***
## Request body
The top-level filter container. At least the `filters` object is required.
Criteria that matching contacts must satisfy.
Free-text job titles to match. Example: `["CTO", "VP Engineering", "Senior Developer"]`
Seniority level IDs. Example: `[4, 5]`
Department names. Example: `["Engineering & Technical"]`
Geographic filters. Each object may include `continent`, `country`, `state`, `city`, and `country_grouping`.
Only return contacts that have specific data available. Example values: `"phone"`, `"work_email"`, `"mobile_phone"`, `"direct_phone"`. See [Contact filters](/v2/filters/contact-filters) for the full list of valid values.
Filter by specific LinkedIn profile URLs.
Free-text search across contact fields. Example: `"Amit"`
**Premium feature.** Filter contacts that have a signal of the specified types. Credits are charged for each signal type that returns results.
Signal types to match. Allowed values: `"allSignals"`, `"promotion"`, `"companyChange"`
Earliest signal date in `YYYY-MM-DD` format. Example: `"2025-01-01"`
Same structure as `include`. Contacts matching these criteria are excluded from results.
Company-level include criteria. Same exclusion structure is available under `filters.companies.exclude`.
Pagination controls.
Page number. Range: `0–1000`.
Results per page. Range: `10–50`.
When `true`, includes contacts with incomplete data in results. Partial profiles may lack some contact details but can still be useful prospects.
**Scale plan feature.** When `true`, filters out contacts whose phone numbers are all marked Do Not Call.
* Contacts with at least one callable phone appear in results.
* Only callable phones are returned - DNC phones are hidden.
* Contacts with only DNC phones are excluded entirely.
Returns `403` on unsupported plans.
***
## Example request
```bash cURL theme={null}
curl --request POST \
--url https://api.lusha.com/prospecting/contact/search \
--header 'api_key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"filters": {
"contacts": {
"include": {
"jobTitles": ["CTO", "Chief Technology Officer", "VP Engineering"],
"seniority": [4, 5],
"departments": ["Engineering & Technical"],
"locations": [
{ "country": "United States", "state": "New York" }
],
"existing_data_points": ["work_email"]
}
}
},
"pages": { "page": 0, "size": 25 },
"excludeDnc": true
}'
```
```json Request body theme={null}
{
"filters": {
"contacts": {
"include": {
"jobTitles": ["CTO", "Chief Technology Officer", "VP Engineering"],
"seniority": [4, 5],
"departments": ["Engineering & Technical"],
"locations": [
{ "country": "United States", "state": "New York" }
],
"existing_data_points": ["work_email"],
"signal": {
"names": ["promotion"],
"startDate": "2025-01-01"
}
}
}
},
"pages": { "page": 0, "size": 25 },
"excludeDnc": true
}
```
***
## Response
### 200 - Success
Unique ID for this search. Pass this value to the Enrich Contacts endpoint as `requestId`.
The page number returned.
Number of results on this page.
Total number of contacts matching your filters across all pages.
Array of matching contacts.
Unique serial ID for this contact in this search response. Use this ID in the Enrich endpoint. Example: `"06de9b18-516d-5512-5cb5-6ec5pb215776"`
Full name of the contact. Example: `"Chris Karageorge"`
Current job title. Example: `"Senior Director of Technical Operations"`
Lusha company identifier. Example: `28054532`
Name of the contact's current employer. Example: `"Lusha"`
Company domain. Example: `"lusha.com"`
Description of the contact's current company.
URL of the company's logo.
Whether this contact has already been revealed by any user in your account.
Signal types detected for this contact. Example: `["promotion", "companyChange"]`
Whether this contact has email addresses available.
Whether this contact has phone numbers available.
Whether a mobile phone is available.
Whether a direct phone number is available.
Whether a work email is available.
Whether a personal email is available.
Whether department data is available for this contact.
Whether seniority data is available for this contact.
Whether location data is available for this contact.
Whether a social profile link (e.g. LinkedIn) is available for this contact.
Whether the company's headcount is available.
Whether the company's revenue range is available.
Whether the company's main industry classification is available.
Whether the company's sub-industry classification is available.
Whether the company's funding data is available.
Whether the company's buyer intent data is available.
Whether the company's technology stack data is available.
Whether the company's city is available.
Whether the company's country is available.
***
## Error codes
| Status | Meaning |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `400` | Validation failed - check your request body for missing or invalid fields. |
| `401` | Unauthorized - your API key is missing or invalid. |
| `403` | Forbidden - your plan does not support this feature (e.g., `excludeDnc` on non-Scale plans, or signal filtering). |
| `429` | Too many requests - you have exceeded the rate limit. |
| `500` | Internal server error - retry with exponential backoff. |
```json 200 theme={null}
{
"requestId": "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7",
"currentPage": 0,
"pageLength": 2,
"totalResults": 142,
"contacts": [
{
"contactId": "06de9b18-516d-5512-5cb5-6ec5pb215776",
"name": "Chris Karageorge",
"jobTitle": "Senior Director of Technical Operations",
"companyId": 28054532,
"companyName": "Lusha",
"fqdn": "lusha.com",
"isShown": false,
"hasEmails": true,
"hasWorkEmail": true,
"hasPhones": true,
"hasMobilePhone": true,
"hasDirectPhone": false,
"signalTypes": ["promotion"]
}
]
}
```
```json 400 theme={null}
{
"statusCode": 400,
"message": "Validation failed",
"errors": ["filters is required"]
}
```
```json 403 theme={null}
{
"statusCode": 403,
"message": "Forbidden",
"errors": ["excludeDnc is not available on your current plan"]
}
```
## OpenAPI
````yaml post /prospecting/contact/search
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: >
Lusha provides a RESTful API that allows you to query a comprehensive
dataset of business profiles and company information.
It is designed for teams building prospecting, enrichment, automation, and
analytics workflows that require accurate, continuously updated business
data. The API supports both real-time and bulk use cases and is suitable for
production environments.
Use the Lusha API to search for new prospects, enrich existing records,
react to real-world changes, and expand coverage using lookalike
recommendations.
*All API requests should be made over HTTPS (SSL), and the response bodies
are delivered in JSON format.*
---
---
**Data Source and Privacy**
Please note that **Lusha is a search platform**, meaning the data provided
is not created or directly managed by us. Instead, it is retrieved from
publicly available sources and through contributions from trusted business
partners.
For more information on how we collect, use, and handle business profiles,
please refer to our [Privacy
Policy](https://lusha.com/legal/privacy-notice/).
----
## Authentication
API keys are required for all API and MCP requests and are tied to your
Lusha account and plan. To access the Lusha API, you must authenticate your
requests using your API key. This key is unique to your account and is used
to identify your usage of the API.
How
to Authenticate:
When making an API call, include your API key in the `api_key` header of the
request.
> You can generate and retrieve your API key
[here](https://dashboard.lusha.com/api/manage-api-keys).
API keys should be stored securely and used only in server-side
environments.
---
### Rate Limiting
Lusha API enforces rate limiting to ensure fair usage and protect against
excessive load.
- **General Rate Limit**: You can make up to 25 requests per second to each
API endpoint
- **Credit Usage API**: Has a specific rate limit of 5 requests per minute
> **Note**: Rate limits may vary based on your account type and subscription
plan.
If you're encountering rate limit issues frequently, please consult with your
account manager or Lusha support team to discuss your specific needs.
**Rate Limit Headers**
To monitor your current rate limit status, check the HTTP response headers
in your API calls:
| Header | Description |
|--------|-------------|
| `x-rate-limit-daily` | The total number of requests allowed per day under
your current plan |
| `x-daily-requests-left` | The number of requests remaining in your daily
quota |
| `x-daily-usage` | The number of requests you have made in the current
daily period |
| `x-rate-limit-hourly` | The total number of requests allowed per hour
under your current plan |
| `x-hourly-requests-left` | The number of requests remaining in your hourly
quota |
| `x-hourly-usage` | The number of requests you have made in the current
hourly period |
| `x-rate-limit-minute` | The total number of requests allowed per minute
under your current plan |
| `x-minute-requests-left` | The number of requests remaining in your
current minute window |
| `x-minute-usage` | The number of requests you have made in the current
minute window |
**Notes on API Rate Limiting**
- If you exceed the rate limit, the API will return a 429 (Too Many
Requests) error.
- To ensure a smooth experience, respect the rate limits defined by your
subscription tier.
- Daily limits vary based on your billing plan — higher tiers have higher
quotas.
- You can programmatically track your usage through these response headers:
- `X-RateLimit-Remaining-Daily`
- `X-RateLimit-Reset-Daily`
- It is strongly recommended to implement logic that:
- Monitors these headers
- Pauses or retries requests accordingly
- Helps avoid hitting the limit and ensures reliable operation
---
## Error Codes
Lusha API uses standard HTTP response codes to indicate the status of your
request. These codes help you understand whether the request was successful
or if there was an issue.
| Status Code | Name | Description |
|-------------|------|-------------|
| **200** | OK | Successful request |
| **400** | Bad Request | Badly formatted request |
| **401** | Unauthorized | The API key is invalid |
| **402** | Payment Required | Your account requires payment |
| **403** | Forbidden | Your account is not active. Please reach out to
support at *support@lusha.com* for assistance |
| **403** | Forbidden | Your pricing version does not support requesting
individual datapoints [revealEmails, revealPhones] |
| **404** | Not Found | The requested endpoint was not found |
| **412** | Precondition Failed | The request failed due to invalid syntax
that was provided. Please make sure to send a full name field that contains
a valid first & last name |
| **429** | Too Many Requests | You've reached your trial limit, please
contact support for upgrade |
| **429** | Too Many Requests | Daily API quota limit exceeded. Limit X
calls per day |
| **429** | Too Many Requests | Hourly API rate limit exceeded. Limit: X
calls per hour. Reset in X seconds |
| **451** | Unavailable For Legal Reasons | We are unable to process this
contact request due to our GDPR regulations |
| **499** | Client Closed Request | Request failed due to request timeout |
| **5XX** | Server Error | There's a problem on Lusha's end |
**Error Response Format**
In case of an error, the response body will contain details about the error:
```json
{
"error": {
"code": 400,
"message": "Invalid request parameters"
}
}
```
Handling errors
- Always ensure your API key is correct and valid
- Pay attention to the specific error message and code to troubleshoot
issues efficiently
- Implement proper error handling and retry logic in your application
- For 5XX errors, implement 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: Enrichment
description: >-
**What is enrichment?**:
Enrichment is the process of adding missing or updated data to existing
contact or company records.
Use enrichment to:
- Complete CRM records
- Improve outbound accuracy and deliverability
- Keep records current as people and companies change
> Enrichment can be performed in real time or in bulk, depending on the
endpoint and use case.
**Available enrichment APIs**
Person enrichment:
- [**Search single
contact**](/apis/openapi/enrichment/searchsinglecontact) - Enrich one
contact at a time
- [**Search multiple
contacts**](/apis/openapi/enrichment/searchmultiplecontacts) - Bulk enrich
contacts
Company enrichment:
- [**Search a single
company**](/apis/openapi/enrichment/searchsinglecompanyv2) - Enrich one
company at a time
- [**Search multiple
companies**](/apis/openapi/enrichment/searchmultiplecompaniesv2) - Bulk
enrich companies
- name: Prospecting - Search & Enrich
description: >
With Lusha's Prospecting API, you can query Lusha's extensive database
based on specific criteria (such as job title, seniority, location, and
more) to retrieve detailed contact and company information.
The Prospecting API is designed to help you generate new records (contacts
or companies) for your CRM system, using filters that align with your
Ideal Customer Profile (ICP).
This process involves three main steps:
| Step | API | Description |
|------|-----|-------------|
| 1 | **Filters API** | Apply filters to refine your search *(Check
available filters under [Contact](/apis/openapi/contact-filters) and
[Company](/apis/openapi/company-filters) Filters)*|
| 2 | **Search API** | Query
[Contacts](/apis/openapi/prospecting-search-and-enrich/searchprospectingcontacts)
or
[Companies](/apis/openapi/prospecting-search-and-enrich/searchprospectingcompanies)
using the available filters |
| 3 | **Enrich API** | Get full details of
[Contacts](/apis/openapi/prospecting-search-and-enrich/enrichprospectingcontacts)
and
[Companies](/apis/openapi/prospecting-search-and-enrich/enrichprospectingcompanies)
from the search results |
x-tag-expanded: true
- name: Contact Filters
description: Available filters for contact searches
x-parent-tag: Prospecting
- name: Company Filters
description: Available filters for company searches
x-parent-tag: Prospecting
- name: Signals
description: >-
With Lusha’s Signals API, you can enrich your contacts and companies with
timely insights that highlight key account and prospect changes. Signals
help you identify moments of opportunity - from job moves and promotions
to company growth and new initiatives - so you can engage prospects and
customers at exactly the right time. Easily integrate signal data into
enrichment flows, CRM systems, or automation workflows to keep pipelines
and customer records always up to date.
x-tag-expanded: true
- name: Lookalikes
description: >-
Lusha's Lookalikes API helps you discover similar contacts and companies
based on your existing data. Get AI-powered suggestions for new prospects
that match your ideal customer profile.
[**Contact Lookalikes**](/apis/openapi/lookalikes/getcontactlookalikes) -
Find similar contacts based on role, seniority, and industry patterns.
[**Company Lookalikes**](/apis/openapi/lookalikes/getcompanylookalikes)-
Discover companies with similar firmographics and characteristics.
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 |
> **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) |
---
- name: Account Management
description: >
Manage your account and monitor usage.
Use this endpoint to:
- Monitor credit usage
- Understand consumption patterns
- Align API usage with plan limits
- Support governance and production operations
Account-level insights are especially important for teams running Lusha at
scale or across multiple systems.
paths:
/prospecting/contact/search:
post:
tags:
- Prospecting - Search & Enrich
summary: Search Contacts
description: >
Search for contacts using various filters. This is step 2 of the
prospecting process.
*Endpoint*: **(POST) https://api.lusha.com/prospecting/contact/search**
---
##### Signal Filtering (Premium Feature)
Filter contacts by signal types to find prospects at key career moments.
> **Note:** This is a premium feature. Credits are charged for each signal type that returns results.
---
##### DNC Filtering (Scale Feature)
Use `excludeDnc: true` at the top level of the request body to filter
out contacts whose phone numbers are all marked Do Not Call.
- Contacts with **at least one callable phone** appear in results - Only
callable phones are shown — DNC phones are hidden - Contacts with **only
DNC phones** are excluded entirely
> **Note**: Returns **403** on unsupported plans.
operationId: searchProspectingContacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSearchRequest'
examples:
basicContactSearch:
summary: Basic contact search with filters
value:
pages:
page: 0
size: 20
filters:
contacts:
include:
departments:
- Engineering & Technical
- Marketing
seniority:
- 4
- 5
existing_data_points:
- phone
- work_email
- mobile_phone
locations:
- continent: North America
country: United States
city: New York
state: New York
country_grouping: na
signals:
names:
- allSignals
- promotion
- companyChange
startDate: '2025-11-01'
exclude:
departments:
- Human Resources
companies:
include:
names:
- Apple
- Microsoft
locations:
- country: United States
technologies:
- Salesforce
- Amazon Web Services
mainIndustriesIds:
- 4
- 5
subIndustriesIds:
- 101
intentTopics:
- Digital Sales
sizes:
- min: 100
max: 1000
revenues:
- min: 10000000
max: 100000000
sicCodes:
- '1011'
- '1021'
naicsCodes:
- '11'
- '21'
exclude: {}
simpleExample:
summary: Simple search example
value:
pages:
page: 0
size: 10
filters:
contacts:
include:
departments:
- Sales
withSearchText:
summary: Contact search with searchText filter
value:
pages:
page: 0
size: 50
filters:
contacts:
include:
searchText: Amit
departments:
- Engineering & Technical
exclude:
searchText: Ronen
companies:
include:
searchText: finance marketing in Germany DE
dncFilterExample:
summary: Exclude DNC contacts — Scale only (LD-2313)
value:
pages:
page: 0
size: 20
excludeDnc: true
filters:
contacts:
include:
linkedinUrls:
- https://www.linkedin.com/in/justin-pernitz
- https://www.linkedin.com/in/andrewbarrettbettcher
- >-
https://www.linkedin.com/in/aitor-moreno-artola-11a2a985
companies: {}
employeesInLinkedInContactExample:
summary: >-
Filter contacts by company LinkedIn employee count (staging
only)
value:
pages:
page: 0
size: 20
filters:
contacts:
include:
departments:
- Sales
companies:
include:
employeesInLinkedIn:
min: 500
responses:
'200':
description: Search results with contact IDs
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSearchResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden — DNC filter not available on your current plan
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 403
message: >-
Exclude DNC is not supported on your current plan. Please
contact support or your account manager for assistance.
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
ContactSearchRequest:
type: object
properties:
includePartialContact:
type: boolean
description: >
When set to true, includes contacts with partial information in the
search results.
Partial contacts may have incomplete data but can still be valuable
prospects.
default: true
example: false
excludeDnc:
type: boolean
description: >
When `true`, excludes contacts whose phones are all marked Do Not
Call (DNC). Contacts with at least one callable phone appear in
results; only callable phones are returned (DNC phones are hidden).
Contacts with only DNC phones are excluded entirely.
default: false
example: true
pages:
$ref: '#/components/schemas/PaginationParams'
filters:
type: object
properties:
contacts:
$ref: '#/components/schemas/ContactFilters'
companies:
$ref: '#/components/schemas/CompanyFilters'
required:
- filters
ContactSearchResponse:
type: object
properties:
requestId:
type: string
description: The unique request ID used for subsequent enrichment requests
currentPage:
type: number
description: The current page of the search results
pageLength:
type: number
description: The number of results on the page
totalResults:
type: number
description: The total number of search results
contacts:
type: array
items:
$ref: '#/components/schemas/ContactSearchData'
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'
PaginationParams:
type: object
properties:
page:
type: number
description: Page number (0-1000)
minimum: 0
maximum: 1000
default: 0
size:
type: number
description: Page size (10-50)
minimum: 10
maximum: 50
default: 20
ContactFilters:
type: object
properties:
include:
type: object
properties:
departments:
type: array
items:
type: string
example:
- Engineering & Technical
seniority:
type: array
items:
type: integer
example:
- 4
- 5
existing_data_points:
type: array
items:
type: string
example:
- phone
- work_email
locations:
type: array
items:
$ref: '#/components/schemas/LocationFilter'
jobTitles:
type: array
items:
type: string
example:
- CTO
- Chief Technology Officer
- VP Engineering
- Senior Developer
linkedinUrls:
type: array
description: Filter contacts by LinkedIn profile URLs
items:
type: string
example:
- https://www.linkedin.com/in/justin-pernitz
- https://www.linkedin.com/in/andrewbarrettbettcher
searchText:
type: string
description: Free-text search across contact fields
example: Amit
signal:
type: object
description: >-
Filter contacts by signal types (premium filter - charges apply
per signal type)
properties:
names:
type: array
description: Signal types to filter by
items:
type: string
enum:
- allSignals
- promotion
- companyChange
example:
- promotion
- companyChange
startDate:
type: string
format: date
description: Start date for signal detection (YYYY-MM-DD format)
example: '2025-11-01'
exclude:
type: object
description: Same structure as include, for exclusion filters
CompanyFilters:
type: object
properties:
include:
type: object
properties:
names:
type: array
items:
type: string
example:
- Apple
domains:
type: array
items:
type: string
example: lusha.com
locations:
type: array
items:
type: object
properties:
country:
type: string
example: United States
technologies:
type: array
items:
$ref: '#/components/schemas/CompanyTechnology'
example:
- name: Amazon
intentTopics:
type: array
items:
type: string
example:
- Digital Sales
sizes:
type: array
items:
$ref: '#/components/schemas/CompanySizeRange'
revenues:
type: array
items:
$ref: '#/components/schemas/RevenueRange'
sicCodes:
type: array
items:
type: string
example:
- '1011'
- '1021'
naicsCodes:
type: array
items:
type: string
example:
- '11'
- '21'
mainIndustriesIds:
type: array
items:
type: number
example:
- 4
- 5
subIndustriesIds:
type: array
items:
type: number
example:
- 101
searchText:
type: string
description: Free-text search across company fields
example: Finance Marketing in Germany DE
excludePartialCompanies:
type: boolean
example: false
companyLocations:
type: array
description: >
Filter by company **site-level office locations** as reported by
LinkedIn.
This includes all physical office locations where the company
has a presence.
> **Important:** This is distinct from the `locations` filter,
which matches against
**HQ location only**. Use `companyLocations` when you want to
find companies
with offices in a specific region regardless of where their
headquarters is.
items:
$ref: '#/components/schemas/CompanyLocationFilter2'
example:
- country: United States
state: California
- country: Germany
employeesInLinkedIn:
$ref: '#/components/schemas/EmployeesInLinkedInFilter'
signal:
type: object
description: >
Filter companies by signal types (premium filter - charges apply
per signal type).
For signal filtering. See the [Signal
Options](https://docs.lusha.com/apis/openapi/signals/getsignaloptions)
for available signal types.
properties:
names:
type: array
description: Signal types to filter by
items:
type: string
enum:
- allSignals
- websiteTrafficIncrease
- websiteTrafficDecrease
- itSpendIncrease
- itSpendDecrease
- headcountIncrease1m
- headcountDecrease1m
- headcountIncrease3m
- headcountDecrease3m
- headcountIncrease6m
- headcountDecrease6m
- headcountIncrease12m
- headcountDecrease12m
- surgeInHiring
- surgeInHiringByDepartment
- surgeInHiringByLocation
- riskNews
- commercialActivityNews
- corporateStrategyNews
- financialEventsNews
- peopleNews
- marketIntelligenceNews
- productActivityNews
example:
- commercialActivityNews
- financialEventsNews
startDate:
type: string
format: date
description: Start date for signal detection (YYYY-MM-DD format)
example: '2025-11-01'
exclude:
type: object
description: Same structure as include, for exclusion filters
ContactSearchData:
type: object
properties:
contactId:
type: string
description: A unique serial contact ID generated for each search response
example: 06de9b18-516d-5512-5cb5-6ec5pb215776
isShown:
type: boolean
description: >-
Indicates whether the contact was already revealed by any of the
account users
example: false
name:
type: string
description: The full name of the contact
example: Chris Karageorge
jobTitle:
type: string
description: The job title held by the person at their current company
example: Senior Director of Technical Operations
companyId:
type: number
description: A unique identifier for a Lusha company
example: 28054532
companyName:
type: string
description: The name of the company where the person currently works
example: Lusha
fqdn:
type: string
description: The fqdn of the company
example: lusha.com
companyDescription:
type: string
description: A description of the company
example: >-
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.\n\nLusha’s Sales Streaming Platform is built around Sales
Playlists that continuously fill up with their ideal prospects –
think “Spotify for sales.” With AI doing the heavy lifting, Lusha
uncovers great-fit leads salespeople never knew existed and executes
tailored, perfectly timed cadences that get meetings booked. And the
more you use Lusha, the smarter it gets.\n\nWith Sales Streaming,
salespeople spend most of their time face-to-face with relevant
prospects, driving 4-6X more business.
logoUrl:
type: string
description: The URL of the company's logo
example: >-
https://logo.lusha.co/brightdata/year=2024/month=04/day=30/j_lvlvj2vh1yv1ee0hye.b098e8301e8d32c12d1c8949a0624ba44761f995.file_lvlwjpb62juzpfz0l2.logo_cached.jpg
hasCompanyEmployeesCount:
type: boolean
hasCompanyRevenue:
type: boolean
hasCompanyMainIndustry:
type: boolean
hasCompanySubIndustry:
type: boolean
hasCompanyFunding:
type: boolean
hasCompanyIntent:
type: boolean
hasCompanyTechnologies:
type: boolean
hasDepartment:
type: boolean
hasSeniority:
type: boolean
hasContactLocation:
type: boolean
hasSocialLink:
type: boolean
hasEmails:
type: boolean
hasWorkEmail:
type: boolean
hasPrivateEmail:
type: boolean
hasPhones:
type: boolean
hasMobilePhone:
type: boolean
hasDirectPhone:
type: boolean
hasCompanyCity:
type: boolean
hasCompanyCountry:
type: boolean
signalTypes:
type: array
description: Types of signals detected for this contact
items:
type: string
example:
- companyChange
- promotion
LocationFilter:
type: object
properties:
continent:
type: string
example: North America
country:
type: string
example: United States
city:
type: string
example: New York
state:
type: string
example: New York
country_grouping:
type: string
example: na
CompanyTechnology:
type: object
properties:
name:
type: string
example: salesforce
description: Technology name used by the company
required:
- name
CompanySizeRange:
type: object
properties:
min:
type: number
example: 1
max:
type: number
example: 10
RevenueRange:
type: object
properties:
min:
type: number
example: 1
max:
type: number
example: 1000000
CompanyLocationFilter2:
type: object
description: |
Site-level office location filter. At least `country` is required.
`state` without `country` is not supported.
required:
- country
properties:
country:
type: string
example: United States
state:
type: string
example: California
EmployeesInLinkedInFilter:
type: object
description: |
Filter companies by LinkedIn-reported employee count.
Both `min` and `max` are optional — provide either or both.
properties:
min:
type: integer
format: int64
description: Minimum employee count (inclusive)
example: 100
max:
type: integer
format: int64
description: Maximum employee count (inclusive)
example: 5000
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
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:
RateLimit-Limit:
description: The total number of allowed requests per second
schema:
type: integer
RateLimit-Remaining:
description: The number of remaining requests in the current window
schema:
type: integer
RateLimit-Reset:
description: The time (in seconds) until the rate limit quota is reset
schema:
type: integer
X-RateLimit-Remaining-Daily:
description: The number of remaining requests for your daily quota
schema:
type: integer
X-RateLimit-Reset-Daily:
description: The time when your daily quota will reset
schema:
type: integer
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 500
message: Internal server error. Please try again later.
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.
````