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

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

https://api.lusha.com/v2/person
▶ Common Use Cases
  • • Form enrichment
  • • CRM completion
  • • Outbound personalization

Company

https://api.lusha.com/v2/company
▶ Common Use Cases
  • • Account enrichment
  • • Routing, scoring, territory logic
  • • Market analysis & segmentation

Signals

https://api.lusha.com/v2/signals
▶ Common Use Cases
  • • Job change tracking
  • • Company updates signals
  • • News event alerts

Lookalikes

https://api.lusha.com/v2/recommendations
▶ Common Use Cases
  • • Market expansion
  • • Similar account discovery
  • • Prospect recommendations
Webhooks APINEW

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.

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

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
402Payment RequiredYour account requires payment
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
License
Proprietary
Terms of Service
Languages
Servers
Mock server
https://docs.lusha.com/_mock/apis/openapi
Production server
https://api.lusha.com

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:

Company enrichment:

Operations

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:

StepAPIDescription
1Filters APIApply filters to refine your search (Check available filters under Contact and Company Filters)
2Search APIQuery Contacts or Companies using the available filters
3Enrich APIGet full details of Contacts and Companies from the search results
Operations

Contact Filters

Available filters for contact searches

Operations

Company Filters

Available filters for company searches

Operations

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.

Operations

Get Signal Options

Request

Retrieve available signal options for a specific entity type (contact or company). This endpoint returns the list of signal types you can filter by when enriching contacts or companies.

Endpoints:

  • Contacts: GET /api/signals/filters/contact
  • Companies: GET /api/signals/filters/company

Available Signal Types

For contacts:

  • allSignals - All available contact signal types
  • promotion - Job title promotions
  • companyChange - Company changes

For companies:

  • allSignals - All available company signal types

Hiring & Workforce:

  • surgeInHiring - Overall hiring activity increase
  • surgeInHiringByDepartment - Department-specific hiring surges
  • surgeInHiringByLocation - Location-specific hiring surges

Headcount Trends:

SignalDescription
headcountIncrease1m / headcountDecrease1m1-month employee count changes
headcountIncrease3m / headcountDecrease3m3-month employee count changes
headcountIncrease6m / headcountDecrease6m6-month employee count changes
headcountIncrease12m / headcountDecrease12m12-month employee count changes

Technology & Digital Presence:

  • websiteTrafficIncrease - Website traffic growth
  • websiteTrafficDecrease - Website traffic decline
  • itSpendIncrease - IT spending increase
  • itSpendDecrease - IT spending decrease
Security
ApiKeyAuth
Path
objectTypestringrequired

The type of object to get signal options for

Enum"contact""company"
Example: contact
curl -i -X GET \
  https://docs.lusha.com/_mock/apis/openapi/api/signals/filters/contact \
  -H 'api_key: YOUR_API_KEY_HERE'

Responses

List of available signal types for the specified object type

Bodyapplication/json
signalsArray of strings
Example: ["promotion","companyChange"]
objectTypestring
Example: "contact"
Response
application/json
{
  "signals": [
    "promotion",
    "companyChange",
    "allSignals"
  ],
  "objectType": "contact"
}

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-01-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": {
    "115889": { … }
  },
  "endDate": "2025-07-31",
  "startDate": "2025-01-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-01-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-01-01"
  }'

Responses

Contact signals search results

Bodyapplication/json
contactsobject

Map of user-provided IDs to contact signals

endDatestring(date)

End date of the signal period

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

Start date of the signal period

Example: "2025-01-01"
creditChargedinteger

Number of credits charged for this request

Example: 2
Response
application/json
{
  "contacts": {
    "123321": { … }
  },
  "endDate": "2025-07-31",
  "startDate": "2025-01-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""websiteTrafficIncrease""websiteTrafficDecrease""itSpendIncrease""itSpendDecrease""headcountIncrease1m""headcountDecrease1m""headcountIncrease3m""headcountDecrease3m""headcountIncrease6m"
Example: null
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": [
      "websiteTrafficIncrease"
    ],
    "startDate": "2025-01-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-01-01"
creditChargedinteger

Number of credits charged for this request

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

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""websiteTrafficIncrease""websiteTrafficDecrease""itSpendIncrease""itSpendDecrease""headcountIncrease1m""headcountDecrease1m""headcountIncrease3m""headcountDecrease3m""headcountIncrease6m"
Example: ["itSpendIncrease"]
startDatestring(date)

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

Example: "2025-01-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": [
      "itSpendIncrease"
    ],
    "startDate": "2025-01-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-01-01"
creditChargedinteger

Number of credits charged for this request

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

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.

Operations

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:

MethodEndpointPurpose
POST/api/subscriptionsCreate subscriptions (bulk supported)
GET/api/subscriptionsList all subscriptions
GET/api/subscriptions/{id}Get subscription by ID
PATCH/api/subscriptions/{id}Update subscription
POST/api/subscriptions/deleteDelete subscriptions (bulk supported)
POST/api/subscriptions/{id}/testTest subscription delivery
GET/api/audit-logsGet webhook delivery logs
GET/api/audit-logs/statsGet delivery statistics
GET/api/account/secretGet account webhook secret
POST/api/account/secret/regenerateRegenerate account secret

Webhook Setup Verification: When creating subscriptions, Lusha sends a GET request with a challenge parameter to verify your endpoint. Your endpoint must return {"challenge": "value"} with HTTP 200.

Webhook Delivery Acknowledgment: When receiving webhook deliveries (POST requests), your endpoint must acknowledge with a specific response format. See the Create Subscription endpoint for the required acknowledgment structure.

Rate Limits
OperationLimit
API Requests100 requests/minute per account
Create Subscriptions25 items per request
Delete Subscriptions25 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=abc123xyz

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

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

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:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["entityType must be one of: contact, company"]
}
FieldTypeDescription
statusCodenumberHTTP status code
messagestringError message
errorsstring[]Detailed error messages (optional)
Operations

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.

Operations
Terms
Copyright © Lusha. All rights reserved.