API overview

Lusha’s V3 REST API lets you search for new prospects, enrich existing records, react to real-world changes, and expand coverage with AI-powered recommendations. It’s built for prospecting, enrichment, automation, and analytics workflows, and every endpoint accepts batches, so real-time and bulk use the same calls.

You’re viewing the V3 documentation - the current version. Use the version switcher at the top of the sidebar to jump to V2 (Legacy). The toggle is scoped to API docs and won’t appear on other tabs. Moving over from V2? Start with the migration guide.

Quickstart

Get your API key

Generate and manage your key in the Lusha dashboard. Your key is tied to your account and plan.

Treat your API key like a password. Use it only in server-side environments - never ship it in browser or mobile code.

Make your first request

Pass the key in the api_key header on every call. This searches for four contacts by different identifiers in a single request:

curl --request POST \
  --url https://api.lusha.com/v3/contacts/search \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contacts": [
      { "clientReferenceId": "my-ref-1", "firstName": "Orit", "lastName": "Shilvock", "companyDomain": "lusha.com" },
      { "clientReferenceId": "my-ref-2", "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger" },
      { "clientReferenceId": "my-ref-3", "email": "gal.ashkelon@lusha.com" }
    ],
    "options": { "includePartialProfiles": true }
  }'

import requests

response = requests.post(
    "https://api.lusha.com/v3/contacts/search",
    headers={"api_key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "contacts": [
            {"clientReferenceId": "my-ref-1", "firstName": "Orit",
             "lastName": "Shilvock", "companyDomain": "lusha.com"},
            {"clientReferenceId": "my-ref-2",
             "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger"},
            {"clientReferenceId": "my-ref-3", "email": "gal.ashkelon@lusha.com"},
        ],
        "options": {"includePartialProfiles": True},
    },
)

print(response.json())

const response = await fetch("https://api.lusha.com/v3/contacts/search", {
  method: "POST",
  headers: {
    api_key: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contacts: [
      { clientReferenceId: "my-ref-1", firstName: "Orit", lastName: "Shilvock", companyDomain: "lusha.com" },
      { clientReferenceId: "my-ref-2", linkedinUrl: "https://www.linkedin.com/in/shmulikwillinger" },
      { clientReferenceId: "my-ref-3", email: "gal.ashkelon@lusha.com" },
    ],
    options: { includePartialProfiles: true },
  }),
});

console.log(await response.json());

Attach your own clientReferenceId to each item and it’s echoed back on the matching result - so you can align responses with your own records without depending on Lusha’s IDs.

Enrich what you found

Search returns matches and what’s available on each one. Pass the returned contact id to Enrich Contacts to reveal emails and phone numbers - that reveal is the step that spends credits.

Try it live

Run real requests against your account from the browser.

Authentication

How to pass your key securely and what happens when it’s missing.

Migrating from V2

What changed, and how to move across.

API modules

Search

Find contacts or companies using known identifiers.

Enrich

Retrieve full profile data for contacts or companies by ID.

Search & Enrich

Find and retrieve full contact or company data in a single call.

Prospecting

Filter-based search across contacts and companies.

Lookalikes

AI-powered recommendations for similar contacts and companies.

Signals

Real-world activity data for contacts and companies.

Signal Score

A single [0, 1] buying-activity score per contact or company.

Buying Group

The buying committee at each target account, labelled by persona role.

Conversations

Search recorded sales calls and fetch speaker-attributed transcripts.

Website Visits

Companies ranked by website-visit signals for your tracked domains.

Filters

Discover valid filter values for prospecting.

Webhooks

Real-time signal notifications via HTTP callbacks.

Account

Usage, credits, rate limits, and pricing.

Authentication

All requests require an API key linked to your Lusha account and plan, passed in the api_key request header.


Base URL	`https://api.lusha.com/v3/`
Auth header	`api_key: YOUR_API_KEY`
Transport	HTTPS only
Format	JSON request and response bodies

Generate and manage your key in the Lusha dashboard.

Rate limiting

Rate limits are applied per plan across three windows - per minute, per hour, and per day - and vary by account. Every response carries your current standing in the headers below, so you can back off before you hit a 429 rather than after.

Rate limits for the Credit Usage API differ from standard endpoint limits.

Rate limit response headers

Header	Description
`x-rate-limit-daily`	Total requests allowed per day
`x-daily-requests-left`	Requests remaining in your daily quota
`x-daily-usage`	Requests made in the current daily period
`x-rate-limit-hourly`	Total requests allowed per hour
`x-hourly-requests-left`	Requests remaining in your hourly quota
`x-hourly-usage`	Requests made in the current hourly period
`x-rate-limit-minute`	Total requests allowed per minute
`x-minute-requests-left`	Requests remaining in the current minute window
`x-minute-usage`	Requests made in the current minute window

To check your plan’s limits, see the Lusha Help Center or contact your account manager.

Error codes

Lusha uses standard HTTP status codes. Every error response shares the same shape:

{
  "statusCode": 400,
  "message": "Invalid request parameters"
}

Code	Name	Description
`200`	OK	Request was successful
`400`	Bad Request	Request is malformed or missing required fields
`401`	Unauthorized	API key is missing or invalid
`402`	Payment Required	Insufficient credits or payment needed
`403`	Forbidden	Account is inactive. Contact support@lusha.com
`404`	Not Found	Endpoint or resource does not exist
`429`	Too Many Requests	Rate limit or daily quota exceeded
`451`	Unavailable For Legal Reasons	Request blocked due to GDPR regulations
`499`	Client Closed Request	Request timed out before completing
`5XX`	Server Error	Issue on Lusha’s end. Retry with exponential backoff

How to handle errors

Read the message field first - it carries the specific reason.
401 - verify your API key is correct, active, and sent in the api_key header.
429 - wait for the window to reset. Check the rate limit headers to see which window you exhausted.
5XX - retry with exponential backoff rather than immediately.

For the full per-endpoint list, see the error codes reference.

Data source and privacy

Lusha is a search platform. The data provided is not created or directly managed by Lusha. It’s sourced from publicly available information and trusted business partners. For more details on how Lusha collects and handles data, see the Privacy Policy.

Overview

Resources

Endpoints

Quickstart

Try it live

Authentication

Migrating from V2

API modules

Search

Enrich

Search & Enrich

Prospecting

Lookalikes

Signals

Signal Score

Buying Group

Conversations

Website Visits

Filters

Webhooks

Account

Authentication

Rate limiting

Error codes

Data source and privacy

​Quickstart

Try it live

Authentication

Migrating from V2

​API modules

Search

Enrich

Search & Enrich

Prospecting

Lookalikes

Signals

Signal Score

Buying Group

Conversations

Website Visits

Filters

Webhooks

Account

​Authentication

​Rate limiting

​Error codes

​Data source and privacy

Quickstart

API modules

Authentication

Rate limiting

Error codes

Data source and privacy