Search Contacts

Lusha API (2.0.0)

Lusha provides a RESTful API that allows you to query a comprehensive dataset of business profiles and company information.

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.

Authentication

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.

Important Notes

To obtain your API key, please visit the following link: https://dashboard.lusha.com/enrich/api
Your API key is sensitive and should be kept private. Do not share it with anyone outside of your organisation.
The API key is used to track and manage your usage of the API, so ensure it is protected from unauthorised access.

Available Endpoints

Person Enrichment: Get contact information for individuals
Company Enrichment: Get detailed company information
Prospecting: Search and enrich contacts and companies based on specific criteria
Account Management: Monitor your API credit usage

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

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
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

Download OpenAPI description

openapi.json

openapi.yaml

Overview

URL

https://api.lusha.com

Lusha Support

support@lusha.com

Servers

Mock server

https://docs.lusha.com/_mock/apis/openapi/

Production server

https://api.lusha.com/

Person Enrichment

The Person API allows you to look up detailed information about a person using various identifiers, such as their email, LinkedIn URL, full name, company name, or company domain. You can retrieve key data points like Location, Email, Phone number, Social network URLs.

Operations

Company Enrichment

The Company API allows you to retrieve detailed company information based on a company's domain or name.

Operations

Prospecting

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 leads) 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
2	Search API	Query Contacts or Companies using the available filters
3	Enrich API	Get full details of Contacts and Companies from the search results

Important Notes:

The API KEY header is mandatory for every request to our service.
A credit is charged only in the final step (Step 3: Enrich API).

Contact Filters

Available filters for contact searches

Operations

Company Filters

Available filters for company searches

Operations

Contact Search & Enrich

Search and enrich contact data

Operations

Search Contacts

Request

Search for contacts using various filters. This is step 2 of the prospecting process.

Important: No credits are charged for searches. Credits are only charged during enrichment.

Security

ApiKeyAuth

Bodyapplication/jsonrequired

pagesobject(PaginationParams)

offsetobject(OffsetParams)

filtersobjectrequired

filters.contactsobject(ContactFilters)

filters.companiesobject(CompanyFilters)

curl -i -X POST \
  https://docs.lusha.com/_mock/apis/openapi/prospecting/contact/search \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY_HERE' \
  -d '{
    "pages": {
      "page": 0,
      "size": 20
    },
    "offset": {
      "index": 0,
      "size": 40
    },
    "filters": {
      "contacts": {
        "include": {
          "departments": [
            "Engineering & Technical"
          ],
          "seniority": [
            "2"
          ],
          "existing_data_points": [
            "phone",
            "work_email"
          ],
          "locations": [
            {
              "continent": "North America",
              "country": "United States",
              "city": "New York",
              "state": "New York",
              "country_grouping": "na"
            }
          ]
        },
        "exclude": {}
      },
      "companies": {
        "include": {
          "names": [
            "Apple"
          ],
          "locations": [
            {
              "country": "United States"
            }
          ],
          "technologies": [
            "Amazon"
          ],
          "mainIndustriesIds": [
            "1",
            "2"
          ],
          "subIndustriesIds": [
            0
          ],
          "intentTopics": [
            "Digital Sales"
          ],
          "sizes": [
            {
              "min": 1,
              "max": 10
            }
          ],
          "revenues": [
            {
              "min": 1,
              "max": 1000000
            }
          ],
          "sics": [
            "1011",
            "1021"
          ],
          "naics": [
            "11",
            "21"
          ]
        },
        "exclude": {}
      }
    }
  }'

Responses

Search results with contact IDs

Bodyapplication/json

requestIdstring

The unique request ID used for subsequent enrichment requests

currentPagenumber

The current page of the search results

totalResultsnumber

The total number of search results

contactsArray of objects(ContactSearchData)

Response

application/json

{
  "requestId": "string",
  "currentPage": 0,
  "totalResults": 0,
  "contacts": [
    { … }
  ]
}

Enrich Contacts

Request

Enrich contacts from search results. This is step 3 of the prospecting process.

⚠️ 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

Security

ApiKeyAuth

Bodyapplication/jsonrequired

requestIdstringrequired

The requestId generated in the Prospecting Search response (UUID)

Example: "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7"

contactIdsArray of stringsrequired

An array containing the contact IDs for enrichment. Min 1, max 100.

Example: ["37b4c536-eaec-11ef-ad4b-a75f8e9e1484"]

revealEmailsboolean

Set revealEmails=true to retrieve only the email address of the contact. Only available to customers on the Unified Credits pricing plan.

Example: false

revealPhonesboolean

Set revealPhones=true to retrieve only the phone number of the contact. Only available to customers on the Unified Credits pricing plan.

Example: true

curl -i -X POST \
  https://docs.lusha.com/_mock/apis/openapi/prospecting/contact/enrich \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY_HERE' \
  -d '{
    "requestId": "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7",
    "contactIds": [
      "37b4c536-eaec-11ef-ad4b-a75f8e9e1484"
    ]
  }'

Responses

Enriched contact data

Bodyapplication/json

requestIdstring

The requestId that was used in the request

contactsArray of objects

Response

application/json

{
  "requestId": "string",
  "contacts": [
    { … }
  ]
}

Company Search & Enrich

Search and enrich company data

Operations

Account Management

Manage your account and monitor usage

Operations

Lusha API (2.0.0)

Data Source and Privacy

Authentication

How to Authenticate

Important Notes

Available Endpoints

Rate Limiting

Rate Limit Headers

Notes on API Rate Limiting

Error Codes

Error Response Format

Handling Errors

Person Enrichment

Company Enrichment

Prospecting

Contact Filters

Company Filters

Contact Search & Enrich

Search Contacts

Request

Responses

Was this helpful?

Enrich Contacts

Request

Responses

Was this helpful?

Company Search & Enrich

Account Management

Lusha API (2.0.0)

Data Source and Privacy

Authentication

How to Authenticate

Important Notes

Available Endpoints

Rate Limiting

Rate Limit Headers

Notes on API Rate Limiting

Error Codes

Error Response Format

Handling Errors

Person Enrichment

Company Enrichment

Prospecting

Contact Filters

Company Filters

Contact Search & Enrich

Search Contacts

RequestExpand all

Responses

Was this helpful?

Enrich Contacts

Request

Responses

Was this helpful?

Company Search & Enrich

Account Management

Request