> ## 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 Multiple Contacts
> Enrich multiple contacts in a single request. This endpoint allows you to submit a list of contacts
and receive enriched data for each one, including company information.
>##### Endpoint:
```
POST https://api.lusha.com/v2/person
```
>##### Notes
- You can process up to 100 contacts per request.
- Using `personId` provides the most direct way to retrieve contact information.
- At least one of `email`, `linkedinUrl`, or `company`/`domain` with `fullName` is required.
---
⚠️ **Important Notice - Unified Credits Plan Required**
| Parameter | Requirement |
|-----------|-------------|
| `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan |
| Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error |
| Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available |
---
## OpenAPI
````yaml /v2/openapi.json post /v2/person
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:
/v2/person:
post:
tags:
- Enrichment
summary: Search Multiple Contacts
description: >
Enrich multiple contacts in a single request. This endpoint allows you
to submit a list of contacts
and receive enriched data for each one, including company information.
>##### Endpoint:
```
POST https://api.lusha.com/v2/person
```
>##### Notes
- You can process up to 100 contacts per request.
- Using `personId` provides the most direct way to retrieve contact information.
- At least one of `email`, `linkedinUrl`, or `company`/`domain` with `fullName` is required.
---
⚠️ **Important Notice - Unified Credits Plan Required**
| Parameter | Requirement |
|-----------|-------------|
| `revealEmails` and `revealPhones` | Only available to customers on the
**Unified Credits** pricing plan |
| Plan Restriction | Attempting to use these parameters on other plans
will result in a **403 Unauthorized** error |
| Default Behavior | When neither parameter is used, the API returns
**both email addresses and phone numbers**, if available |
---
operationId: searchMultipleContacts
requestBody:
required: true
description: The list of contacts to enrich
content:
application/json:
schema:
$ref: '#/components/schemas/SearchBulkContactsRequest'
examples:
successful_response:
summary: Successful contact lookup
value:
contacts:
- contactId: '1'
personId: '4183886134'
fullName: John Doe
email: john@example.com
companies:
- name: Example Corp
domain: example.com
isCurrent: true
- contactId: '2'
personId: '4183886135'
linkedinUrl: https://www.linkedin.com/in/carolinaportela/
metadata:
revealEmails: true
revealPhones: true
signals:
- promotion
- companyChange
signalsStartDate: '2025-03-01'
partialProfile: true
responses:
'200':
description: The list of enriched contacts with their company details
content:
application/json:
schema:
$ref: '#/components/schemas/BulkPersonResponse'
example:
contacts:
'1':
error: null
isCreditCharged: false
data:
firstName: John
lastName: Doe
fullName: John Doe
companyId: 1586
contactTags: []
emails:
- john.doe@amazon.com
- johndoe@gmail.com
emailAddresses:
- email: john.doe@amazon.com
emailType: work
updateDate: '2025-11-17'
emailConfidence: A+
- email: johndoe@gmail.com
emailType: private
updateDate: '2025-11-17'
emailConfidence: A+
phones:
- +1 555-123-4567
phoneNumbers:
- number: +1 555-123-4567
phoneType: direct
doNotCall: false
updateDate: '2025-11-17'
personId: 1312840528
location:
country: United States
country_iso2: US
continent: North America
is_eu_contact: false
state: Massachusetts
state_code: MA
city: Boston
city_id: 4930956
location_coordinates:
- -71.05976867675781
- 42.358428955078125
jobTitle:
title: Engineering Manager
departments:
- Engineering & Technical
seniority: Manager
socialLinks:
linkedin: https://www.linkedin.com/in/johndoe
xUrl: https://twitter.com/johndoe
jobStartDate: '2022-03-01'
previousJob:
company:
name: TechCorp
domain: techcorp.com
jobTitle:
title: Senior Software Engineer
departments:
- Engineering & Technical
updateDate: '2025-11-17'
linkedinFollowersCount: 2800
linkedinConnectionsCount: 450
linkedinCertifications:
- companyName: AWS
title: AWS Certified Solutions Architect
dateYear: 2023
dateMonth: 8
linkedinCourses:
- school:
name: MIT
degree: Master of Engineering
startDateYear: 2018
endDateYear: 2020
linkedinAwards:
- title: Engineering Excellence Award
companyName: TechCorp
dateYear: 2021
dateMonth: 12
linkedinSkills:
- Cloud Architecture
- Team Leadership
- System Design
'2':
error: null
isCreditCharged: false
data:
firstName: Jane
lastName: Smith
fullName: Jane Smith
companyId: 33222678
contactTags: []
emails:
- jane.smith@lusha.com
emailAddresses:
- email: jane.smith@lusha.com
emailType: work
updateDate: '2025-11-18'
emailConfidence: A+
phones: []
phoneNumbers: []
personId: 3965070011
location:
country: United States
country_iso2: US
continent: North America
is_eu_contact: false
jobTitle:
title: Solutions Engineer
departments:
- Engineering & Technical
seniority: Non-Manager
socialLinks:
linkedin: https://www.linkedin.com/in/janesmith
xUrl: https://twitter.com/janesmith
jobStartDate: '2022-10-17'
previousJob:
company: {}
jobTitle: {}
updateDate: '2025-11-18'
linkedinFollowersCount: 2800
linkedinConnectionsCount: 450
linkedinCertifications:
- companyName: AWS
title: AWS Certified Solutions Architect
dateYear: 2023
dateMonth: 8
linkedinCourses:
- school:
name: MIT
degree: Master of Engineering
startDateYear: 2018
endDateYear: 2020
linkedinAwards:
- title: Engineering Excellence Award
companyName: TechCorp
dateYear: 2021
dateMonth: 12
linkedinSkills:
- Cloud Architecture
- Team Leadership
- System Design
companies:
'1586':
name: Amazon
description: >-
Amazon is guided by four principles: customer obsession
rather than competitor focus, passion for invention,
commitment to operational excellence, and long-term
thinking. We are driven by the excitement of building
technologies, inventing products, and providing services
that change lives. We embrace new ways of doing things,
make decisions quickly, and are not afraid to fail. We
have the scope and capabilities of a large company, and
the spirit and heart of a small one.
Together, Amazonians research and develop new technologies
from Amazon Web Services to Alexa on behalf of our
customers: shoppers, sellers, content creators, and
developers around the world.
Our mission is to be Earth's most customer-centric
company. Our actions, goals, projects, programs, and
inventions begin and end with the customer top of mind.
You'll also hear us say that at Amazon, it's always "Day
1." What do we mean? That our approach remains the same as
it was on Amazon's very first day - to make smart, fast
decisions, stay nimble, invent, and focus on delighting
our customers.
domains:
homepage: amazon.com
email: amazon.com
homepageUrl: https://amazon.com
fqdn: www.amazon.com
location:
city: Seattle
continent: North America
country: United States
rawLocation: 2127 7th Ave.; Seattle, WA 98109, US
countryIso2: US
state: Washington
stateCode: WA
locationCoordinates:
- -122.33206939697266
- 47.60620880126953
companySize:
- 100001
- 10000000
revenueRange:
- 1000000000
- 10000000000
logoUrl: https://logo.lusha.co/amazon-logo.jpg
social:
linkedin: https://www.linkedin.com/company/amazon
crunchbase: https://www.crunchbase.com/organization/amazon
specialities:
- ecommerce
- internet of things platform
- operations
- retail
technologies: null
funding: null
intent:
detectedTopics:
- topicName: Model Based Systems Engineering (MBSE)
metadata:
topicScore: 82
topicTrend: '-4'
topicCount: 1
mainIndustry: Technology, Information & Media
subIndustry: E-Commerce & Marketplace
industryPrimaryGroupDetails:
sics:
- sic: 5961
description: Catalog and mail-order houses
'33222678':
name: Lusha
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.
Lusha'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.
With Sales Streaming, salespeople spend most of their time
face-to-face with relevant prospects, driving 4-6X more
business.
domains:
homepage: lusha.com
email: lusha.com
homepageUrl: https://lusha.com
fqdn: www.lusha.com
location:
city: Boston
continent: North America
country: United States
rawLocation: >-
800 Boylston St; Suite 1410; Boston, Massachusetts
02199, US
countryIso2: US
state: Massachusetts
stateCode: MA
locationCoordinates:
- -71.05976867675781
- 42.358428955078125
companySize:
- 201
- 500
revenueRange: []
logoUrl: https://logo.lusha.co/lusha-logo.jpg
social:
linkedin: https://www.linkedin.com/company/lushadata
crunchbase: https://www.crunchbase.com/organization/lusha
specialities:
- data accuracy
- data availability
- data enrichment
- inside sales
- lead capture
- lead gen
- lead generation
- lead generation software
- lead intelligence
- lead mining
- lead nurturing
- prospecting
- sales enablement
- sales intelligence
technologies: null
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
intent:
detectedTopics:
- topicName: HIPAA Compliance
metadata:
topicScore: 78
topicTrend: '-3'
- topicName: Software Development Lifecycle
metadata:
topicScore: 74
topicTrend: '-1'
- topicName: Asana
metadata:
topicScore: 72
topicTrend: New
- topicName: Agile Transformation
metadata:
topicScore: 71
topicTrend: '+7'
- topicName: Rally Software
metadata:
topicScore: 70
topicTrend: '+8'
- topicName: VersionOne
metadata:
topicScore: 70
topicTrend: '-10'
topicCount: 6
mainIndustry: Technology, Information & Media
subIndustry: Software Development
industryPrimaryGroupDetails:
sics:
- sic: 7371
description: Custom computer programming services
naics:
- naics: 541511
description: Custom Computer Programming Services
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
SearchBulkContactsRequest:
type: object
properties:
contacts:
description: >-
This is a required parameter that should contain a list of contact
objects. Each contact will be processed based on the provided
contact details.
type: array
items:
$ref: '#/components/schemas/ContactSearchBulk'
metadata:
$ref: '#/components/schemas/Metadata'
description: Metadata for the search to filter the results
required:
- contacts
BulkPersonResponse:
type: object
properties:
contacts:
type: object
description: The contacts of the bulk person output, keyed by contactId
additionalProperties:
$ref: '#/components/schemas/ContactResponse'
companies:
type: object
description: The companies of the bulk person output, keyed by companyId
additionalProperties:
$ref: '#/components/schemas/CompanyResponse'
required:
- contacts
- companies
ContactSearchBulk:
type: object
properties:
contactId:
type: string
description: >-
A unique sequential ID to associate with the contact object in the
API response
example: '1234'
personId:
type: string
description: The unique person identifier in Lusha
example: '4183886134'
fullName:
type: string
description: The full name of the person
example: Dustin Moskovitz
location:
type: string
description: The raw location of the person
example: Singapore,Chicago
linkedinUrl:
type: string
description: The LinkedIn URL of the person
example: https://www.linkedin.com/in/dustin/
email:
type: string
description: The email address of the person
example: dustin@lusha.com
companies:
description: >-
Details of the company where the contact is currently employed (or
previously employed if applicable)
type: array
items:
$ref: '#/components/schemas/Company'
required:
- contactId
Metadata:
type: object
properties:
refreshJobInfo:
type: boolean
description: >-
Set this to true to refresh job information for the contact. This
replaces any outdated job details with the most current information.
By default, Lusha returns results for records that have at least one
of the specified contact details (e.g., phone number or email
address).
example: true
filterBy:
type: string
description: >-
Filters the results based on specific contact details. Use the
following options: emailAddresses, phoneNumbers
example: emailAddresses
revealEmails:
type: boolean
description: >
Set `revealEmails=true` to retrieve only the email address of the
contact.
example: true
revealPhones:
type: boolean
description: >
Set `revealPhones=true` to retrieve only the phone number of the
contact.
example: true
signals:
type: array
description: |
Array of signal types to retrieve for the contact.
- `allSignals`: All available signal types
- `promotion`: Promotion signals
- `companyChange`: Company change signals
items:
type: string
enum:
- allSignals
- promotion
- companyChange
example:
- promotion
- companyChange
signalsStartDate:
type: string
format: date
description: >
Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6
months ago if not specified.
example: '2025-03-01'
partialProfile:
type: boolean
description: >
When set to true, returns a simplified contact profile with basic
information only.
default: false
example: true
ContactResponse:
type: object
properties:
error:
$ref: '#/components/schemas/ContactError'
description: The error of the contact
isCreditCharged:
type: boolean
description: Indicates whether a credit charge was made for the contact
example: true
data:
$ref: '#/components/schemas/Contact'
description: The data of the contact
required:
- error
- isCreditCharged
CompanyResponse:
type: object
properties:
name:
type: string
description: The name of the company
example: Lusha
description:
type: string
description: The description of the company
example: >-
Lusha is a company that provides a platform for companies to find
and connect with potential customers.
domains:
type: object
description: The domains of the company
properties:
homepage:
type: string
example: https://www.lusha.com
email:
type: string
example: contact@lusha.com
homepageUrl:
type: string
description: The homepage URL of the company
example: https://www.lusha.com
fqdn:
type: string
description: The FQDN of the company
example: lusha.com
location:
$ref: '#/components/schemas/LocationResponse'
description: The location of the company
companySize:
description: The size of the company
example:
- 100
- 1000
type: array
items:
type: number
revenueRange:
description: The revenue range of the company
example:
- 1000000
- 10000000
type: array
items:
type: number
industryPrimaryGroup:
type: string
description: The industry primary group of the company
example: Software
logoUrl:
type: string
description: The logo URL of the company
example: https://www.lusha.com/logo.png
social:
$ref: '#/components/schemas/SocialResponse'
description: The social links of the company
specialities:
description: The specialities of the company
example:
- Software
- Sales
type: array
items:
type: string
technologies:
description: The technologies of the company
type: array
items:
$ref: '#/components/schemas/CompanyTechnology'
example:
- name: JavaScript
- name: Python
funding:
$ref: '#/components/schemas/FundingData'
description: The funding data of the company
industry:
$ref: '#/components/schemas/CompanyIndustryData'
description: The industry of the company
intent:
$ref: '#/components/schemas/BuyerIntent'
description: The intent of the company
industryPrimaryGroupDetails:
$ref: '#/components/schemas/IndustryPrimaryGroupDetailsResponse'
description: The industry primary group details of the company
required:
- name
- fqdn
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'
Company:
type: object
properties:
name:
type: string
description: The name of the company, Required if no domain.
example: Lusha
domain:
type: string
description: The domain of the company, Required if no name.
example: lusha.com
isCurrent:
type: boolean
description: Indicates whether this is the person's current company
example: true
jobTitle:
type: string
description: The job title of the person at the company
example: Software Engineer
fqdn:
type: string
description: The fully qualified domain name of the company
example: https://lusha.com
companySocialId:
type: string
description: The social ID associated with the company (if available)
example: '1234567890'
required:
- isCurrent
ContactError:
type: object
properties:
code:
type: number
description: The code of the contact error
example: 3
name:
type: string
description: The name of the contact error
example: EMPTY_DATA
message:
type: string
description: The message of the contact error
example: Could not find requested data
Contact:
type: object
properties:
companyId:
type: number
description: A unique identifier for the company on Lusha
example: 123
firstName:
type: string
description: The first name of the person
example: Dustin
lastName:
type: string
description: The last name of the person
example: Moskovitz
fullName:
type: string
description: The full name of the person
example: Dustin Moskovitz
emails:
description: Simple array of email addresses (deprecated - use emailAddresses)
type: array
items:
type: string
example:
- john.doe@example.com
emailAddresses:
description: Detailed email addresses with metadata
type: array
items:
$ref: '#/components/schemas/EmailAddress'
phones:
description: Simple array of phone numbers (deprecated - use phoneNumbers)
type: string
example: +1 555-123-4567
phoneNumbers:
description: Detailed phone numbers with metadata
type: array
items:
$ref: '#/components/schemas/PhoneNumbers'
personId:
type: number
description: The unique person identifier in Lusha
example: 123456
location:
$ref: '#/components/schemas/LocationResponse'
description: The location of the person
jobTitle:
$ref: '#/components/schemas/JobTitle'
description: The job title of the person
socialLinks:
$ref: '#/components/schemas/SocialLinks'
description: The social links of the person
jobStartDate:
type: string
description: The start date at current position
example: '2020-01-01'
previousJob:
$ref: '#/components/schemas/PreviousJobResponse'
description: The previous job of the person
contactTags:
description: Tags associated with the contact
type: array
items:
$ref: '#/components/schemas/ContactTag'
updateDate:
type: string
description: The last update date of the contact data
example: '2020-01-01'
linkedinFollowersCount:
type: integer
description: Number of followers on LinkedIn
example: 1250
linkedinConnectionsCount:
type: integer
description: Number of LinkedIn connections
example: 500
linkedinCertifications:
description: Professional certifications listed on LinkedIn
type: array
items:
$ref: '#/components/schemas/LinkedinCertification'
linkedinCourses:
description: Courses listed on LinkedIn profile
type: array
items:
$ref: '#/components/schemas/LinkedinCourse'
linkedinAwards:
description: Honors and awards listed on LinkedIn profile
type: array
items:
$ref: '#/components/schemas/LinkedinAward'
linkedinSkills:
description: Skills listed on LinkedIn profile
type: array
items:
type: string
example:
- Microsoft Office
- Project Management
- Strategic Planning
required:
- companyId
- firstName
- lastName
- fullName
LocationResponse:
type: object
properties:
country:
type: string
description: The country where the person is located.
example: Israel
countryIso2:
type: string
description: The ISO 3166-1 alpha-2 country code of the person.
example: IL
country_iso2:
type: string
description: The ISO 3166-1 alpha-2 country code of the person.
example: IL
continent:
type: string
description: The continent where the person is located.
example: Asia
rawLocation:
type: string
example: 800 Boylston St, Suite 1410, Boston, MA 02199, US
description: The detailed address.
region:
type: string
description: The region where the person is located.
example: Tel Aviv
city:
type: string
description: The city where the person is located.
example: Tel Aviv
cityId:
type: number
description: The ID of the city where the person is located.
example: 123
state:
type: string
description: The state where the person is located.
example: Tel Aviv
stateCode:
type: string
description: The state code of the person.
example: IL
state_code:
type: string
description: The state code of the person.
example: IL
street:
type: string
description: The street where the person is located.
example: 123 Main St
locationCoordinates:
description: The coordinates of the person.
example:
- 32.0853
- 34.7818
type: array
items:
type: number
isEuContact:
type: boolean
description: Indicates whether the person is in the EU.
example: true
required:
- country
- countryIso2
- continent
- rawLocation
SocialResponse:
type: object
properties:
linkedin:
type: string
description: The LinkedIn URL of the person
example: https://www.linkedin.com/in/dustin/
crunchbase:
type: string
description: The Crunchbase URL of the person
example: https://www.crunchbase.com/person/dustin-moskovitz
twitter:
type: string
description: The Twitter URL of the person
example: https://twitter.com/dustin
facebook:
type: string
description: The Facebook URL of the person
example: https://www.facebook.com/dustin
CompanyTechnology:
type: object
properties:
name:
type: string
example: salesforce
description: Technology name used by the company
required:
- name
FundingData:
type: object
properties:
totalRounds:
type: number
description: The total rounds of the funding data
example: 10
totalRoundsAmount:
type: number
description: The total rounds amount of the funding data
example: 1000000
currency:
type: string
description: The currency of the funding data
example: USD
isIpo:
type: boolean
description: Indicates whether the company is an IPO
example: true
lastFundingEventDate:
type: string
description: The last funding event date of the funding data
example: '2020-01-01'
lastFundingEventAmount:
type: number
description: The last funding event amount of the funding data
example: 1000000
lastFundingEventName:
type: string
description: The last funding event name of the funding data
example: Series A
rounds:
description: The rounds of the funding data
type: array
items:
$ref: '#/components/schemas/FundingDataRound'
required:
- totalRounds
- currency
- isIpo
CompanyIndustryData:
type: object
properties:
mainIndustry:
type: string
description: The main industry of the company
example: Software
subIndustry:
type: string
description: The sub industry of the company
example: Sales
required:
- mainIndustry
- subIndustry
BuyerIntent:
type: object
properties:
topicCount:
type: integer
description: The topic count of the buyer intent
example: 6
detectedTopics:
type: array
description: The detected topics of the buyer intent
items:
$ref: '#/components/schemas/CompanyIntentTopic'
required:
- topicCount
- detectedTopics
IndustryPrimaryGroupDetailsResponse:
type: object
properties:
sicCodes:
description: The SIC codes of the industry primary group
type: array
items:
$ref: '#/components/schemas/CompanySic'
naicsCodes:
description: The NAICS codes of the industry primary group
type: array
items:
$ref: '#/components/schemas/CompanyNaics'
EmailAddress:
type: object
properties:
email:
type: string
description: The email address (alternative to 'address')
example: dustin@lusha.com
address:
type: string
description: The email address (alternative to 'email')
example: dustin@lusha.com
emailType:
type: string
description: The type of email address (alternative to 'type')
example: work
enum:
- work
- private
emailConfidence:
type: string
description: The confidence level of the email address
example: A+
updateDate:
type: string
description: The update date of the email address
example: '2020-01-01'
PhoneNumbers:
type: object
properties:
number:
type: string
description: The phone number
example: '+1234567890'
phoneType:
type: string
description: The type of phone number
example: Mobile
enum:
- Mobile
- Direct
- Phone
doNotCall:
type: boolean
description: Indicates whether the phone number is listed as "Do Not Call" (DNC).
example: false
updateDate:
type: string
description: The update date of the phone number
example: '2020-01-01'
required:
- phoneType
- doNotCall
- updateDate
JobTitle:
type: object
properties:
seniority:
type: string
description: The seniority of the person.
example: Director
title:
type: string
description: The title of the person.
example: Director of Platform
departments:
description: The departments of the person.
example:
- Engineering
- Operations
type: array
items:
type: string
required:
- seniority
- title
- departments
SocialLinks:
type: object
properties:
linkedin:
type: string
description: The LinkedIn URL of the person
example: https://www.linkedin.com/in/dustin/
xUrl:
type: string
description: The Twitter/X profile URL of the person
example: https://twitter.com/dustin
required:
- linkedin
PreviousJobResponse:
type: object
properties:
jobTitle:
$ref: '#/components/schemas/JobTitle'
description: The job title of the person
company:
$ref: '#/components/schemas/Company'
description: The company of the person
required:
- jobTitle
- company
ContactTag:
type: object
properties:
id:
type: string
description: The ID of the contact tag
example: '123'
name:
type: string
description: The name of the contact tag
example: Prospect
color:
type: string
description: The color of the contact tag
example: '#000000'
required:
- id
- name
- color
LinkedinCertification:
type: object
properties:
companyId:
type: integer
description: Company ID that issued the certification
example: 1035
companyName:
type: string
description: Name of the company/organization that issued the certification
example: Microsoft
credentialId:
type: string
description: Credential ID for verification
example: abc123
dateMonth:
description: Month the certification was obtained
example: 6
anyOf:
- type: integer
- type: string
dateYear:
description: Year the certification was obtained
example: 2020
anyOf:
- type: integer
- type: string
expireDateMonth:
description: Month the certification expires
example: 6
anyOf:
- type: integer
- type: string
expireDateYear:
description: Year the certification expires
example: 2025
anyOf:
- type: integer
- type: string
linkedinCompanyId:
type: integer
nullable: true
description: LinkedIn company ID
example: 1441
summary:
type: string
nullable: true
description: Description of the certification
example: Azure fundamentals certification covering cloud concepts
title:
type: string
description: Title/name of the certification
example: 'Microsoft Certified: Azure Fundamentals'
verifyUrl:
type: string
nullable: true
description: URL to verify the certification
example: >-
https://www.youracclaim.com/badges/5ccf865c-dd6e-4dcc-9184-c8999d31f83d
LinkedinCourse:
type: object
properties:
activities:
type: string
nullable: true
description: Activities
degree:
type: string
nullable: true
description: Degree
endDate:
type: string
nullable: true
description: End date
endDateMonth:
description: End month
oneOf:
- type: integer
nullable: true
- type: string
nullable: true
endDateYear:
description: End year
oneOf:
- type: integer
nullable: true
- type: string
nullable: true
fieldOfStudy:
type: object
nullable: true
description: Field of study object
properties:
id:
type: string
nullable: true
name:
type: string
nullable: true
grade:
type: string
nullable: true
description: Grade
incompleteEducation:
type: boolean
nullable: true
description: Incomplete education flag
notes:
type: string
nullable: true
description: Notes
school:
type: object
nullable: true
description: School information
properties:
createdAt:
type: string
nullable: true
id:
type: string
nullable: true
logoUrl:
type: string
nullable: true
name:
type: string
nullable: true
updatedAt:
type: string
nullable: true
startDate:
type: string
nullable: true
description: Start date
startDateMonth:
description: Start month
oneOf:
- type: number
nullable: true
- type: string
nullable: true
startDateYear:
description: Start year
oneOf:
- type: number
nullable: true
- type: string
nullable: true
linkedinSchoolId:
type: number
nullable: true
description: LinkedIn school ID
LinkedinAward:
type: object
properties:
companyName:
type: string
nullable: true
description: Name of the organization that gave the award
example: Columbia Southern University
dateDay:
oneOf:
- type: number
- type: string
description: Day the award was received
example: 15
dateMonth:
oneOf:
- type: number
- type: string
description: Month the award was received
example: 7
dateYear:
oneOf:
- type: number
- type: string
description: Year the award was received
example: 2023
linkedinCompanyId:
type: string
nullable: true
description: LinkedIn company ID
summary:
type: string
nullable: true
description: Description of the award
example: Certificate of Recognition for Exceptional Teaching
title:
type: string
description: Title/name of the award
example: Raising the Bar Award
FundingDataRound:
type: object
properties:
announcedOn:
type: string
description: The announced on date of the funding data
example: '2020-01-01'
leadInvestors:
description: The lead investors of the funding data
example:
- Investor 1
- Investor 2
type: array
items:
type: string
currency:
type: string
description: The currency of the funding data
example: USD
title:
type: string
description: The title of the funding data
example: Series A
moneyRaised:
type: number
description: The money raised of the funding data
example: 1000000
required:
- currency
- title
CompanyIntentTopic:
type: object
properties:
topicName:
type: string
example: Remote Sales
description: Name of the intent topic
metadata:
$ref: '#/components/schemas/CompanyIntentTopicMetadata'
required:
- topicName
- metadata
CompanySic:
type: object
properties:
sicCodes:
type: number
example: 1234
description:
type: string
example: Software Publishing
required:
- sic
- description
CompanyNaics:
type: object
properties:
naicsCodes:
type: number
example: 541511
description:
type: string
example: Custom Computer Programming Services
required:
- naics
- description
CompanyIntentTopicMetadata:
type: object
properties:
topicScore:
type: number
example: 83
description: Relevance score for the intent topic
topicTrend:
type: string
example: '-5'
description: Trend of the topic (e.g., +1, -5, New)
required:
- topicScore
- topicTrend
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
Forbidden:
description: Forbidden - account inactive or feature not available
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
featureNotAvailable:
summary: Feature not available for pricing plan
value:
statusCode: 403
message: >-
Your pricing version does not support requesting individual
datapoints [revealEmails, revealPhones]
subscriptionLimitReached:
summary: Subscription limit reached
value:
statusCode: 403
message: Maximum subscriptions limit reached for your account
dncNotSupported:
summary: DNC filter not supported on current plan
value:
statusCode: 403
message: >-
Exclude DNC is not supported on your current plan. Please
contact support or your account manager for assistance.
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.
````