The first name of the person
- Search Single Contact
Lusha API Documentation
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.
Person
▶ Common Use Cases
- • Form enrichment
- • CRM completion
- • Outbound personalization
Company
▶ Common Use Cases
- • Account enrichment
- • Routing, scoring, territory logic
- • Market analysis & segmentation
Signals
▶ Common Use Cases
- • Job change tracking
- • Company updates signals
- • News event alerts
Lookalikes
▶ Common Use Cases
- • Market expansion
- • Similar account discovery
- • Prospect recommendations
Filters
Account
Subscribe to real-time notifications when contacts change jobs or companies experience key business events.
View Documentation →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.
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. API keys should be stored securely and used only in server-side environments.
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-DailyX-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
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:
{
"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
Enrichment
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 - Enrich one contact at a time
- Search multiple contacts - Bulk enrich contacts
Company enrichment:
- Search a single company - Enrich one company at a time
- Search multiple companies - Bulk enrich companies
Request
Find and enrich a single contact using various search criteria. You can search by name, email, LinkedIn URL, or company information.
GET https://api.lusha.com/v2/personYou must provide either:
emailORlinkedinUrlORfirstNameANDlastNameAND (companyNameORcompanyDomain)
- Provide as much information as possible for better results
- Use
refreshJobInfo=trueto get the latest employment data - Use
filterByparameter to specify what contact details you need - Include the
signalsparameter to retriever contact signals (If no signals data is found for the specified period, thesignalsobject will be empty but still present in the response.)- When requesting signals, you can optionally specify a start date using
signalsStartDate. - Signals data is optional. If you don't include the
signalsparameter, no signals data will be returned.
- When requesting signals, you can optionally specify a start date using
⚠️ 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 |
The LinkedIn URL of the person
Set to true to refresh and update the job details for the person. This ensures that outdated job information is replaced with the most recent data.
Filters results based on specific contact details. Available options:
phoneNumbers: Only return contacts with phone numbersemailAddresses: Only return contacts with email addresses
By default, results will include contacts with at least one contact detail.
Set revealEmails=true to retrieve only the email address of the contact.
Set revealPhones=true to retrieve only the phone number of the contact.
Array of signal types to retrieve for the contact.
allSignals: All available signal typespromotion: Promotion signalscompanyChange: Company change signals
Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.
- Mock serverhttps://docs.lusha.com/_mock/apis/openapi/v2/person
- Production serverhttps://api.lusha.com/v2/person
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.lusha.com/_mock/apis/openapi/v2/person?firstName=Dustin&lastName=Moskovitz&companyName=Lusha&companyDomain=lusha.com&email=dustin%40lusha.com&linkedinUrl=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fdustin%2F&refreshJobInfo=true&filterBy=phoneNumbers&revealEmails=true&revealPhones=true&signals=promotion&signalsStartDate=2025-03-01&partialProfile=true' \
-H 'api_key: YOUR_API_KEY_HERE'{ "contact": { "error": null, "isCreditCharged": false, "data": { … } } }
Request
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.
POST https://api.lusha.com/v2/person- You can process up to 100 contacts per request.
- At least one of
email,linkedinUrl, orcompany/domainwithfullNameis 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 |
The list of contacts to enrich
This is a required parameter that should contain a list of contact objects. Each contact will be processed based on the provided contact details.
A unique sequential ID to associate with the contact object in the API response
The LinkedIn URL of the person
- Mock serverhttps://docs.lusha.com/_mock/apis/openapi/v2/person
- Production serverhttps://api.lusha.com/v2/person
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://docs.lusha.com/_mock/apis/openapi/v2/person \
-H 'Content-Type: application/json' \
-H 'api_key: YOUR_API_KEY_HERE' \
-d '{
"contacts": [
{
"contactId": "1",
"fullName": "John Doe",
"email": "john@example.com",
"companies": [
{
"name": "Example Corp",
"domain": "example.com",
"isCurrent": true
}
]
},
{
"contactId": "2",
"linkedinUrl": "https://www.linkedin.com/in/carolinaportela/"
}
],
"metadata": {
"revealEmails": true,
"revealPhones": true,
"signals": [
"promotion",
"companyChange"
],
"signalsStartDate": "2025-03-01",
"partialProfile": true
}
}'{ "contacts": { "1": { … }, "2": { … } }, "companies": { "1586": { … }, "33222678": { … } } }
Array of signal types to retrieve for the company.
allSignals: All available signal typesnewsEvent: Company related events
See Signal Filters for complete list of available signals and their categories
Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.
- Mock serverhttps://docs.lusha.com/_mock/apis/openapi/v2/company
- Production serverhttps://api.lusha.com/v2/company
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.lusha.com/_mock/apis/openapi/v2/company?domain=example.com&company=Lusha&companyId=1234567890&signals=itSpendIncrease&signalsStartDate=2025-03-01&partialCompany=false' \
-H 'api_key: YOUR_API_KEY_HERE'{ "data": { "id": 123, "description": "Lusha is the sales intelligence platform designed to help businesses get their next customers.", "domain": "lusha.com", "employees": "201 - 500", "founded": "August 1, 2011", "fqdn": "www.lusha.com", "logoUrl": "https://logo.lusha.co/logo.jpg", "name": "Lusha", "revenueRange": [ … ], "mainIndustry": "Technology", "subIndustry": "Software", "social": { … }, "address": "North America United States Boston 800 Boylston St , Suite 1410 , Boston, Massachusetts 02199, US Massachusetts US MA -71.05976867675781,42.358428955078125 ", "location": { … }, "categories": [ … ], "industryPrimaryGroupDetails": { … }, "website": "https://lusha.com", "specialities": [ … ], "funding": { … }, "intent": { … }, "technologies": [ … ] }, "errors": { "message": "Something went wrong" }, "meta": {} }
Request
Search for multiple companies in a single request. Provide a list of companies with identifiers like domain names or company IDs.
POST https://api.lusha.com/bulk/company/v2- At least one of
domain,company, orcompanyIdis required. - You can process up to 100 companies per request.
The list of companies to search
A unique sequential ID associated with each company. This ID is used to correlate the provided company object with the API response
Array of signal types to retrieve for the companies.
allSignals: All available signal typesnewsEvent: Company related eventssurgeInHiring: Overall hiring activity increase
See Signal Filters for complete details on available signals and their categories
Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.
- Mock serverhttps://docs.lusha.com/_mock/apis/openapi/v2/company
- Production serverhttps://api.lusha.com/v2/company
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://docs.lusha.com/_mock/apis/openapi/v2/company \
-H 'Content-Type: application/json' \
-H 'api_key: YOUR_API_KEY_HERE' \
-d '{
"companies": [
{
"id": "1",
"name": "Lusha"
},
{
"id": "2",
"domain": "google.com"
}
]
}'{ "1": { "id": 33222678, "lushaCompanyId": "16303253", "name": "Lusha", "companySize": [ … ], "fqdn": "www.lusha.com", "founded": "2016", "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.\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": "https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg", "industryPrimaryGroupDetails": { … }, "linkedin": "https://www.linkedin.com/company/lushadata", "mainIndustry": "Technology, Information & Media", "subIndustry": "Software Development", "city": "Boston", "state": "Massachusetts", "country": "United States", "countryIso2": "US", "continent": "North America", "rawLocation": "800 Boylston St; Suite 1410; Boston, Massachusetts 02199, US", "crunchbase": "https://www.crunchbase.com/organization/lusha", "specialities": [ … ], "funding": { … }, "intent": { … } }, "2": { "id": 1441, "lushaCompanyId": "10117615", "name": "Google", "companySize": [ … ], "revenueRange": [ … ], "fqdn": "www.google.com", "description": "A problem isn't truly solved until it's solved for all. Googlers build products that help create opportunities for everyone, whether down the street or across the globe. Bring your insight, imagination and a healthy disregard for the impossible. Bring everything that makes you unique. Together, we can build for everyone.\n\nCheck out our career opportunities at goo.gle/3DLEokh", "logoUrl": "https://logo.lusha.co/coresignal/202405/c/82/c822c1b63853ed273b89687ac505f9fa", "industryPrimaryGroupDetails": { … }, "linkedin": "https://www.linkedin.com/company/google", "mainIndustry": "Technology, Information & Media", "subIndustry": "Software Development", "city": "Mountain View", "state": "California", "country": "United States", "countryIso2": "US", "continent": "North America", "rawLocation": "1600 Amphitheatre Parkway; Mountain View, CA 94043, US", "crunchbase": "https://www.crunchbase.com/organization/g-pay", "specialities": [ … ], "intent": { … } } }
Prospecting - Search & Enrich
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:
Signals
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.
Lookalikes
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 - Find similar contacts based on role, seniority, and industry patterns.
Company Lookalikes- Discover companies with similar firmographics and characteristics.
Webhooks
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.
Key Features:
- Real-time contact & company signal notifications
- Bulk subscription management (up to 25 items per request)
- Secure delivery with HMAC-SHA256 signatures
- Automatic URL verification during setup
- 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 Verification: When creating subscriptions, Lusha sends a GET request with a
challengeparameter. Your endpoint must return{"challenge": "value"}with HTTP 200.
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
Webhook Verification:
When creating or updating a subscription, Lusha verifies your webhook URL by sending a GET request with a challenge query parameter.
Verification Request:
GET https://your-webhook-url.com?challenge=abc123xyzExpected Response (200 OK):
{
"challenge": "abc123xyz"
}Requirements:
- Return HTTP 200 status
- Return Content-Type: application/json
- Echo back the exact challenge value
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:
- Extract the
X-Lusha-SignatureandX-Lusha-Timestampheaders - Concatenate:
timestamp + "." + JSON.stringify(payload) - Compute HMAC-SHA256 using your webhook secret
- Compare the computed signature with the received signature
Example (Node.js):
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
creditsChargedfield 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:
{
"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) |
Account Management
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.