Skip to content
Documentation/
/
Get Contact Signals by ID...

Lusha API

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
  • Signals: Retrieve signals data for contacts and companies

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:

HeaderDescription
x-rate-limit-dailyThe total number of requests allowed per day under your current plan
x-daily-requests-leftThe number of requests remaining in your daily quota
x-daily-usageThe number of requests you have made in the current daily period
x-rate-limit-hourlyThe total number of requests allowed per hour under your current plan
x-hourly-requests-leftThe number of requests remaining in your hourly quota
x-hourly-usageThe number of requests you have made in the current hourly period
x-rate-limit-minuteThe total number of requests allowed per minute under your current plan
x-minute-requests-leftThe number of requests remaining in your current minute window
x-minute-usageThe 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 CodeNameDescription
200OKSuccessful request
400Bad RequestBadly formatted request
401UnauthorizedThe API key is invalid
403ForbiddenYour account is not active. Please reach out to support at support@lusha.com for assistance
403ForbiddenYour pricing version does not support requesting individual datapoints [revealEmails, revealPhones]
404Not FoundThe requested endpoint was not found
412Precondition FailedThe 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
429Too Many RequestsYou've reached your trial limit, please contact support for upgrade
429Too Many RequestsDaily API quota limit exceeded. Limit X calls per day
429Too Many RequestsHourly API rate limit exceeded. Limit: X calls per hour. Reset in X seconds
451Unavailable For Legal ReasonsWe are unable to process this contact request due to our GDPR regulations
499Client Closed RequestRequest failed due to request timeout
5XXServer ErrorThere'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

Terms of Service

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

StepAPIDescription
1Filters APIApply filters to refine your search
2Search APIQuery Contacts or Companies using the available filters
3Enrich APIGet full details of Contacts and Companies from the search results

Important Notes:

  • The API KEY header is mandatory for every request to our service.

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

Company Search & Enrich

Search and enrich company data

Operations

Account Management

Manage your account and monitor usage

Operations

Signal Filters

Operations

Signals

Operations

Get Contact Signals by IDs

Request

Retrieve signals data for a list of contact IDs. This endpoint allows you to get recent activities and signals for up to 100 contacts per request.

Endpoint: (POST) https://api.lusha.com/api/signals/contacts

Default Behavior:

  • Returns signals from the last 6 months by default
  • Use startDate to customize the timeframe
  • Each signal type requested counts towards credit usage
Security
ApiKeyAuth
Bodyapplication/jsonrequired
contactIdsArray of integers[ 1 .. 100 ] itemsrequired

List of contact IDs to retrieve signals for

Example: [115889]
signalsArray of stringsrequired

Types of signals to retrieve

Items Enum"allSignals""promotion""companyChange"
Example: ["promotion","companyChange"]
startDatestring(date)

Start date for signal retrieval (YYYY-MM-DD format)

Example: "2025-03-01"
curl -i -X POST \
  https://docs.lusha.com/_mock/apis/openapi/api/signals/contacts \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY_HERE' \
  -d '{
    "contactIds": [
      115889
    ],
    "signals": [
      "promotion",
      "companyChange"
    ],
    "startDate": "2025-03-01"
  }'

Responses

Contact signals retrieved successfully

Bodyapplication/json
contactsobject

Map of contact IDs to their signals

endDatestring(date)

End date of the signal period

Example: "2025-07-31"
startDatestring(date)

Start date of the signal period

Example: "2025-03-01"
creditChargedinteger

Number of credits charged for this request

Example: 2
Response
application/json
{
  "contacts": {
    "property1": { … },
    "property2": { … }
  },
  "endDate": "2025-07-31",
  "startDate": "2025-03-01",
  "creditCharged": 2
}

Search Contact Signals

Request

Search for contact signals using identifiers like LinkedIn URL, email, or name + company. This endpoint combines search and signal enrichment in a single request.

Endpoint: (POST) https://api.lusha.com/api/signals/contacts/search

Search Requirements: Each contact can be identified by:

  • Contact ID
  • LinkedIn URL
  • Email address
  • Full name + Company (name or domain)

Default Behavior:

  • Returns signals from the last 6 months by default
  • Contacts are matched based on provided identifiers
  • Returns both contact data and associated signals
Security
ApiKeyAuth
Bodyapplication/jsonrequired
contactsArray of objectsrequired

List of contact identifiers to search for

contacts[].​idstringrequired

A unique sequential ID to associate with the contact object in the API response

Example: "12345"
contacts[].​social_linkstring(uri)

LinkedIn profile URL

Example: "https://www.linkedin.com/in/ron-nabet"
contacts[].​full_namestring

Full name of the contact

Example: "Ron Nabet"
contacts[].​emailstring(email)

Email address

Example: "dustin@lusha.com"
contacts[].​companiesArray of objects

Company associations

signalsArray of stringsrequired

Types of signals to retrieve

Items Enum"allSignals""promotion""companyChange"
Example: ["promotion","companyChange"]
startDatestring(date)

Start date for signal retrieval (YYYY-MM-DD format)

Example: "2025-03-01"
curl -i -X POST \
  https://docs.lusha.com/_mock/apis/openapi/api/signals/contacts/search \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY_HERE' \
  -d '{
    "contacts": [
      {
        "id": "123321",
        "social_link": "https://www.linkedin.com/in/ron-nabet"
      }
    ],
    "signals": [
      "promotion",
      "companyChange"
    ],
    "startDate": "2025-03-01"
  }'

Responses

Contact signals search results

Bodyapplication/json
contactsobject

Map of contact IDs to their signals

endDatestring(date)

End date of the signal period

Example: "2025-07-31"
startDatestring(date)

Start date of the signal period

Example: "2025-03-01"
creditChargedinteger

Number of credits charged for this request

Example: 2
Response
application/json
{
  "contacts": {
    "property1": { … },
    "property2": { … }
  },
  "endDate": "2025-07-31",
  "startDate": "2025-03-01",
  "creditCharged": 2
}

Get Company Signals by IDs

Request

Retrieve signals data for a list of company IDs. This endpoint allows you to get recent activities and signals for up to 100 companies per request.

Endpoint: (POST) https://api.lusha.com/api/signals/companies

Default Behavior:

  • Returns signals from the last 6 months by default
  • Use startDate to customize the timeframe
Security
ApiKeyAuth
Bodyapplication/jsonrequired
companyIdsArray of integers[ 1 .. 100 ] itemsrequired

List of company IDs to retrieve signals for

Example: [3416]
signalsArray of stringsrequired

Types of signals to retrieve

Items Enum"allSignals""headcountGrowth""newJobsOpen""totalJobsOpen"
Example: ["headcountGrowth","newJobsOpen","totalJobsOpen"]
startDatestring(date)

Start date for signal retrieval (YYYY-MM-DD format)

Example: "2025-03-01"
curl -i -X POST \
  https://docs.lusha.com/_mock/apis/openapi/api/signals/companies \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY_HERE' \
  -d '{
    "companyIds": [
      3416
    ],
    "signals": [
      "headcountGrowth",
      "newJobsOpen",
      "totalJobsOpen"
    ],
    "startDate": "2025-03-01"
  }'

Responses

Company signals retrieved successfully

Bodyapplication/json
companiesobject

Map of company IDs to their signals

endDatestring(date)

End date of the signal period

Example: "2025-07-31"
startDatestring(date)

Start date of the signal period

Example: "2025-02-01"
creditChargedinteger

Number of credits charged for this request

Example: 3
Response
application/json
{
  "companies": {
    "property1": { … },
    "property2": { … }
  },
  "endDate": "2025-07-31",
  "startDate": "2025-02-01",
  "creditCharged": 3
}

Search Company Signals

Request

Search for company signals using identifiers like domain, company name, or ID. This endpoint combines search and signal enrichment in a single request.

Endpoint: (POST) https://api.lusha.com/api/signals/companies/search

Search Requirements: Each company must have at least one identifier:

  • Company ID (as string)
  • Company name
  • Company domain

Default Behavior:

  • Returns signals from the last 6 months by default
  • Companies are matched based on provided identifiers
Security
ApiKeyAuth
Bodyapplication/jsonrequired
companiesArray of objects[ 1 .. 100 ] itemsrequired

List of company identifiers to search for

companies[].​idstringrequired

A unique sequential ID to associate with the company object in the API response

Example: "12345"
companies[].​namestring

Company name

Example: "Lusha"
companies[].​domainstring

Company domain

Example: "lusha.com"
signalsArray of stringsrequired

Types of signals to retrieve

Items Enum"allSignals""headcountGrowth""newJobsOpen""totalJobsOpen"
Example: ["headcountGrowth","newJobsOpen","totalJobsOpen"]
startDatestring(date)

Start date for signal retrieval (YYYY-MM-DD format)

Example: "2025-03-01"
curl -i -X POST \
  https://docs.lusha.com/_mock/apis/openapi/api/signals/companies/search \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY_HERE' \
  -d '{
    "companies": [
      {
        "id": "12344321",
        "domain": "lusha.com"
      }
    ],
    "signals": [
      "headcountGrowth",
      "newJobsOpen"
    ],
    "startDate": "2025-03-01"
  }'

Responses

Company signals search results

Bodyapplication/json
companiesobject

Map of company IDs to their signals

endDatestring(date)

End date of the signal period

Example: "2025-07-31"
startDatestring(date)

Start date of the signal period

Example: "2025-02-01"
creditChargedinteger

Number of credits charged for this request

Example: 3
Response
application/json
{
  "companies": {
    "property1": { … },
    "property2": { … }
  },
  "endDate": "2025-07-31",
  "startDate": "2025-02-01",
  "creditCharged": 3
}
Terms
Copyright © Lusha. All rights reserved.