Skip to main content
Lusha provides these RESTful API endpoint groups:Enrichment API - Search and enrich contact and company records. V3 uses a search-then-enrich pattern: first search by identifier to get a non-PII preview, then enrich to reveal emails, phones, and firmographic data. A combined Search and Enrich endpoint is also available for single-step workflows.Prospecting API - Filter-based queries across Lusha’s full database. Filter by job title, seniority, department, location, company size, revenue, industry, technologies, and signals to build targeted contact and company lists. Returns up to 50,000 results per query (1,000 pages × 50 results).Signals API - Real-time buying intent and market intelligence data. Retrieve contact signals (job changes, promotions) and company signals (headcount changes, hiring surges, website traffic, IT spend, news events) by ID or by identifier. Can also be used as a filter inside Search and Prospecting requests.Lookalikes API - AI-powered contact and company recommendations based on seed inputs. Uses session-based deduplication so repeated calls return new results without overlap. Sessions persist for 30 days.Tables API - Create and manage persistent tables of contacts or companies. Save results into a table directly from Prospecting, Enrich, Signals, or Lookalike calls by passing tableId, or manage tables, rows, and enrichment columns directly through dedicated endpoints. Tables are shared with the Workspace UI - changes made through one surface show up on the other.Webhooks API - Subscribe to real-time push notifications when contacts change jobs or companies experience key business events. Supports bulk subscription management, HMAC-SHA256 signature verification, automatic retries, and delivery audit logs. Includes an opt-out notification endpoint for GDPR/CCPA compliance workflows.Buying Group API - Map the buying committee within a set of companies. Supply up to 25 companies by domain or Lusha company ID and get back contacts labelled by persona role (decision_maker, potential_champion, end_user) as previews. Pass the returned contact IDs to Enrich Contacts to reveal emails and phones. The Decision Makers API now routes to this endpoint.Signal Score API - Score contacts or companies by their active buying signals, returning a single [0, 1] value plus the signal breakdown behind it. Accepts up to 100 records per call.ICP Fit Score API - Score contacts or companies against 1-3 of your Target Profiles (ICPs), returning a [0, 1] fit score plus the profile each record fits best. Accepts up to 100 records per call.Conversations API - Search the sales calls recorded by Lusha Conversations for your account and fetch speaker-attributed transcripts. Search returns metadata, AI summaries, action items, risks, objections, and coaching analysis.Website Visitors API - Identify and filter companies that have visited your website. Query traffic across your tracked domains and filter by engagement score, session depth, unique visitors, and geography to surface high-intent accounts. Returns company previews you can pass directly to Enrich Companies for full firmographic data.Account usage, credits, and pricing are covered by a separate Account API endpoint (GET /v3/account/usage).
V3 is the current production version and is recommended for all new integrations. All V3 endpoints are under https://api.lusha.com/v3/. V2 is still operational but is approaching deprecation - see the Migration Guide for details on what changed.
  • All requests must be made over HTTPS.
  • Responses are returned in JSON format.
  • Include your API key in the api_key request header on every call.
Pass your API key in the api_key header of every request. You can generate and manage your key in the Lusha dashboard. Store your key securely and only use it in server-side environments - never expose it in client-side code.
V3 separates data retrieval into two steps:
  1. Search - Look up contacts or companies by identifier (LinkedIn URL, email, name + company, domain, or Lusha ID). Returns a non-PII preview with a has field listing available data points and a canReveal field showing what can be unlocked and the credit cost.
  2. Enrich - Pass the IDs from search results to reveal full data (emails, phones, firmographics).
You can also use the Search and Enrich endpoint to combine both steps in a single call. Billing applies at both steps.
Waterfall Reveal is an enhancement to Enrich Contacts. When Lusha’s own data has no match for a field, it falls through to your enabled third-party providers to try to fill the gap - extra reach on hard-to-match contacts, on top of standard enrichment.How it works:
  • If Data Waterfall is enabled on your account, with specific providers turned on under Account > Waterfall in the Lusha dashboard, the waterfall runs automatically on every Enrich Contacts call - you don’t need to pass anything to trigger it.
  • Pass waterfallEnabled: false to opt a specific call out.
  • reveal still controls which fields come back; waterfallEnabled only controls whether the fallback runs for this call at all.
  • If Data Waterfall is off, or no providers are enabled, waterfallEnabled has no effect either way.
  • Lusha determines the provider query order - it isn’t caller-configurable.
  • Use of Data Waterfall is subject to Lusha’s Supplementary Terms.
Any one of the following per contact:
  • Lusha contact id
  • linkedinUrl
  • email
  • firstName + lastName + companyName or companyDomain
Up to 100 contacts per request.
Any one of the following per company:
  • Lusha company id
  • name
  • domain
Up to 100 companies per request.
Use Prospecting when you want to discover net-new contacts or companies matching your Ideal Customer Profile (ICP). Unlike Enrichment (which looks up known records), Prospecting queries Lusha’s full database using filter criteria and returns paginated results you can then enrich.Contact filters include: job title, seniority, department, location, existing data points, signals, and company attributes like size, revenue, industry, and technologies.Company filters include: size, revenue, industry, SIC/NAICS codes, technologies, locations, funding, and signals.Pass tableId in the request body to also save matching results into an existing table.
You can filter on a wide range of attributes:Contact-level: job title, normalized job title, seniority, department, location (city/state/country/continent), existing data points (e.g. work_email, phone), LinkedIn URLs, free-text search (searchText), and signal types.Company-level: name, domain, size (employee range), revenue range, industry/sub-industry, SIC codes, NAICS codes, technologies (with OR/AND logic), funding details, locations (HQ or site-level offices), LinkedIn employee count, and signal types.Both include and exclude filters are supported. Use the Filter endpoints to discover valid values before building your query.
The Signals API provides real-time market intelligence and activity data for contacts and companies.Contact signals: promotion, companyChangeCompany signals: headcount changes (1m/3m/6m/12m increase or decrease), surgeInHiring, surgeInHiringByDepartment, surgeInHiringByLocation, websiteTrafficIncrease, websiteTrafficDecrease, itSpendIncrease, itSpendDecrease, linkedinFollowersIncrease, linkedinFollowersDecrease, 7 news signal categories: riskNews, commercialActivityNews, corporateStrategyNews, financialEventsNews, peopleNews, marketIntelligenceNews, productActivityNews, and intent: linkedinActivityIntent, newIntentTopic, intentScoreIncrease, intentScoreDecrease, intentTopicRemoved.You can retrieve signals by Lusha IDs or by identifiers (LinkedIn URL, email, name + company/domain). Signals can also be used as filters in Search and Prospecting requests. Use startDate to scope results to a specific timeframe (default: last 6 months). maxResultsPerSignal is optional and caps results per signal type per entity.Company signals also support sub-filters: newsEventTypes, hiringByDepartments, hiringByLocations, intentCategories, and intentTopics to narrow results without separate requests.Pass tableId in the request body to also save matched results into an existing table and populate the Signals column.
Four company signal types track week-over-week changes in what a company is researching:
  • newIntentTopic - the company started researching a topic it had no activity on the previous week
  • intentScoreIncrease / intentScoreDecrease - the topic’s score went up or down compared to the previous week, with changeRatePercent
  • intentTopicRemoved - the topic dropped below the activity threshold, so it no longer has a score
Scores run from 0 to 100 - a high score means the company is researching the topic more than usual. Data refreshes weekly.To get them:
  1. Search the topic catalog with GET /v3/companies/signals/filters/intentTopics?query=salesforce. It returns up to 50 matching topic names and is free.
  2. Call POST /v3/companies/signals with the intent types in signalTypes and the exact topic names in filters.include.intentTopics.
A few things to know:
  • allSignals does not include the four intent types - you have to name them.
  • Every topic in the catalog is available - the topics selected in your dashboard don’t apply.
  • A topic that isn’t in the catalog returns 400 INVALID_FILTER_VALUE.
  • Intent signals are charged like every other company signal, per matched signal via showSignalsCompany.
  • They’re available on the signals lookup only - not in Prospecting or signal search.
See Intent signals.
The Lookalikes API uses AI to find contacts or companies similar to a set of seeds you provide.For contacts, seed with LinkedIn URLs, emails, Lusha IDs, or name + company (5–100 seeds required). For companies, seed with domains or LinkedIn URLs.Results use session-based deduplication via dedupeSessionId - omit it on your first request and the server generates one. Pass it on subsequent requests to get more results without repeats. Sessions are active for 30 days from last use.Use the returned IDs with the Enrich endpoints to get full contact or company data, or pass tableId to save results directly into an existing table.
The Buying Group API (POST /v3/contacts/buying-group) identifies and prioritizes the buying committee within a set of target companies. Rather than pulling every contact at an account and guessing who matters, it returns contact previews grouped by company and pre-labelled by role.Supply up to 25 companies by domain or Lusha company id. For each company, the model scores and labels contacts with one or more persona roles:
  • decision_maker - has budget or sign-off authority
  • potential_champion - likely internal advocate for the purchase
  • end_user - likely day-to-day user of the product
Optional request fields:
  • personas - filter to specific roles; omit to get all three
  • contactsLimit - cap on contacts returned per company (default 60)
  • clientReferenceId - optional token on each company entry, echoed back on the matching result
Each returned contact includes the same non-PII preview shape as Search Contacts (has, canReveal), plus a roles array and a score (0-1) reflecting relevance to the assigned role. Results are paginated via pagination.page / pagination.size in the request body.Use the returned contact id values with POST /v3/contacts/enrich to reveal emails and phones for the people you want to prioritize.Billing: 1 credit per contact record returned, via the buyingGroupContact action. Each record includes name, title, company, LinkedIn, and roles, with no emails or phones. Emails and phones are charged separately when you reveal them through Enrich Contacts, at the normal reveal rates. Credits are charged per record, not per person - if the same person appears at more than one company in the request, each record is charged.The Decision Makers API (POST /v3/contacts/decision-makers) now routes to this endpoint and is billed the same way. See the Buying Group overview.
The ICP Fit Score API scores how well any list of contacts or companies fits your Target Profiles (ICPs) - a CRM export, a CSV, or prospecting results.It works in two steps:
  1. Call GET /v3/icp/profiles to list the Target Profiles you can see - your own, plus any an admin has shared with the account. Filter with the optional status (active | disabled) and access (private | shared) query parameters. This call is free.
  2. Pass 1-3 active profile IDs as targetProfileIds to POST /v3/companies/icp-fit-score or POST /v3/contacts/icp-fit-score, with 1-100 records per call.
Identify companies by exactly one of id, domain, name, or email. Identify contacts by one of id, linkedinUrl, email, or firstName + lastName + (companyName | companyDomain). Add an optional clientReferenceId to match results back to your data.Each scored record returns:
  • icpFitScore - the best fit across the requested profiles, from 0 to 1
  • topProfile - the profile the record fits best
  • profileScores - the score for each profile, only when you request more than one
Records that can’t be resolved return NOT_FOUND, and records with no score available return NO_SCORE. See the ICP Fit Score overview.
They answer different questions. ICP Fit Score measures how closely a record matches your Target Profiles - is this a good fit? Signal Score measures how much buying activity is happening around the record right now - is this a good time?Both accept the same identifiers and up to 100 records per call, so you can score the same list with both. In the Lusha app, the two combine into the Lead Score on recommendations. See Signal Score and ICP Fit Score.
The Conversations API surfaces the sales conversations recorded by Lusha Conversations for your account. It has two endpoints:
  • POST /v3/account/conversations/search - search conversations. Returns per-conversation metadata plus an AI summary, coaching analysis, and chapters, along with action items, risks, objections, and competitor mentions. Transcripts are not included.
  • GET /v3/account/conversations/{conversationId}/transcript - return the speaker-attributed, timestamped transcript for a single conversation, as an ordered list of segments.
Search has two modes on one contract:
  • Keyword mode - supply query (1-500 chars) to rank conversations by transcript content. All other filters are ignored.
  • Filter mode - omit query and use the structural filters: dateFrom/dateTo (date-only YYYY-MM-DD), contactNames, companyDomains (matches on domain, not display name - resolve names to domains first), meetingTitles, and conversationIds.
Paginate via page (starts at 1) and pageSize (1-100, default 25). An empty body is valid and returns the first page of your account’s conversations. pageSize above 100 returns a 400 (it is not silently clamped), and malformed or partial dates also return a 400.Only conversations belonging to your account whose processing has completed are returned. summary, coaching, and chapters come from an asynchronous post-call pipeline - a null/empty value means analysis isn’t ready yet, not that nothing was found. A null severity on a risk or objection means the pipeline didn’t assess it, not “low”. On the transcript endpoint, a single 404 covers all of: the conversation doesn’t exist, its processing hasn’t completed, or it belongs to another account.Use the id from a search result to fetch that conversation’s transcript. See the Conversations overview.
The Tables API lets you create and manage persistent, spreadsheet-like tables of contacts or companies inside Lusha. Tables have configurable columns - default Lusha fields, CRM fields, Signals, AI-generated fields, and score columns - and are shared with the Workspace UI, so a table built via API shows up there immediately, and vice versa.There are two ways to work with tables:
  • Save results directly. Pass tableId on a Prospecting, Enrich, Signals, or Lookalike call. Results are returned as usual, and a tableWrite object confirms what was saved to the table.
  • Manage tables explicitly. Create a table, add or remove rows (entities), add or run enrichment columns, and read rows back - all via dedicated endpoints under /v3/contacts/tables/... and /v3/companies/tables/....
To get a tableId, either create a table (the response returns one) or list your existing tables - there’s no way to guess or predict one.Ownership: every table-route call requires owner.email, which must resolve to an existing user on the account tied to your API key. It’s sent in the request body (owner: { email }) on POST/PATCH calls, and as a ?email= query parameter on GET/DELETE calls that carry no body.Limits: up to 500 entity IDs per add/remove call, 50,000 entities per table, 500 tables per account.Billing: creating, listing, updating, and deleting tables is free, as is listing/adding/removing columns. Reading rows (GET .../entities) is billed per row returned. Adding contacts to a table is free; adding companies is billed per newly-added company. Running an enrichment column is billed per row, per the column’s credit tier.
The Website Visitors API (POST /v3/companies/website-visits) returns a paginated list of companies that visited your website within a specified date range (max 3 months).Domains must be configured for tracking in the Lusha dashboard before use - they are resolved to site IDs server-side. If any requested domain is not configured, the entire request fails with a 400 error.Filter results by:
  • Engagement score band: cold, warm, or hot
  • Session metrics: totalSessions, uniqueVisitors, avgSessionMinutes, daysVisited, highIntentPageviews, daysSinceLastVisit
  • Score range: score (1–100)
  • Geography: visitorCountries with include and exclude arrays (ISO 3166-1 alpha-2 codes)
Sort by any metric using sort.by and sort.order (asc or desc). Paginate via limit (max 150) and offset. Each result includes a company firmographic preview (same shape as Search Companies) plus behavioral visit metrics. Pass the returned company id to Enrich Companies for full firmographic data.
Webhooks provide a push-based alternative to polling the Signals API. Subscribe to specific entities (contacts or companies) and Lusha delivers HTTP POST payloads to your endpoint when signals occur.Key capabilities:
  • Bulk subscription creation (up to 25 per request)
  • Supports all contact and company signal types
  • HMAC-SHA256 signature verification for security
  • Automatic retry with exponential backoff (max 3 attempts)
  • Audit logs for delivery monitoring
  • Opt-out subscription endpoint for data removal compliance
Your endpoint must respond with HTTP 2xx and a JSON acknowledgment within 10 seconds. Subscriptions auto-disable after max retries are exceeded but can be reactivated via the update endpoint.
All endpoints return JSON. Example V3 contact search response snippet:
Yes. Default limits:
  • General endpoints: 25 requests per second
  • Account Usage API: 5 requests per minute
  • Webhooks API: 100 requests per minute
Rate limit status is returned in response headers (x-rate-limit-daily, x-daily-requests-left, x-rate-limit-hourly, x-hourly-requests-left, x-rate-limit-minute, x-minute-requests-left, and their usage counterparts). Contact your account manager if you frequently hit limits.Tables endpoints follow the same general rate limits, with their own separate caps on batch size and table size - see “What is the Tables API?” above.
Lusha uses standard HTTP status codes. Common ones:Error response format:
Tables error bodies use a slightly different shape: { "message": "...", "code": <status>, ... }.
Credits are consumed per action:
  • Search (contact or company): charged per successful result via api_search
  • Enrich contacts: charged per revealed field (revealEmail, revealPhone) via per-datapoint pricing
  • Enrich companies: charged per successful result via reveal_company; additional revealable fields (e.g. employeesByDepartment, competitors) are charged separately per result
  • Signals: charged per matched signal per result
  • Lookalikes: charged per result returned
  • Buying Group: 1 credit per contact record returned via buyingGroupContact. Emails and phones are charged separately when revealed through Enrich Contacts
  • ICP Fit Score: listing Target Profiles is free. Scoring costs 1 credit per scored contact or company, regardless of how many profiles it’s scored against - a score of 0 is charged. NOT_FOUND and NO_SCORE entries are not charged
  • Tables: creating, listing, updating, deleting tables, and managing columns is free. Adding contacts to a table is free; adding companies is charged per newly-added company. Reading rows is charged per row returned. Running an enrichment column is charged per row, per the column’s credit tier
  • Webhooks: charged when signals are detected and delivered; retries do not incur additional charges
Check billing.creditsCharged in any response to see what was consumed. Use the Account Usage endpoint to monitor your balance.
Yes. Use the Lusha Postman Workspace to test endpoints with live examples. You can also test webhook delivery without consuming credits using the Test Subscription endpoint (POST /api/subscriptions/{id}/test).
Use the Filter endpoints before building your prospecting queries:
  • GET /v3/contacts/prospecting/filters - lists available contact filter types
  • GET /v3/contacts/prospecting/filters/{filterType} - returns valid values for a specific filter (e.g. departments, seniority, countries, locations)
  • GET /v3/companies/prospecting/filters - lists available company filter types
  • GET /v3/companies/prospecting/filters/{filterType} - returns valid values (e.g. sizes, revenues, industriesLabels, technologies)
Some filters require a query parameter (e.g. locations, technologies, names).
There’s no way to predict a tableId in advance - you get one from the API itself, either by:
  • Creating a table (POST /v3/contacts/tables or /v3/companies/tables) - the 201 response returns data.tableId
  • Listing existing tables (POST /v3/contacts/tables/list or /v3/companies/tables/list) - each item in the response includes its own tableId
Once you have it, pass it as the {table_id} path parameter on other Tables endpoints, or as the tableId body field on Prospecting, Enrich, Signals, or Lookalike calls.
Key changes in V3:
  • Search-then-enrich pattern - Search is now a separate billable step that returns previews before you commit to enrichment
  • New endpoint paths - All V3 enrichment endpoints are under /v3/contacts/ and /v3/companies/
  • Bulk by default - V3 endpoints natively accept arrays of up to 100 records
  • Lookalikes redesign - New session-based deduplication, expanded seed identifier types, and renamed fields (contactId instead of id in results)
  • Company enrich - New revealable fields: employeesByDepartment, employeesByLocation, employeesBySeniority, competitors
  • Signals are optional per-request - maxResultsPerSignal is now optional (previously required in v2.1.0)
  • Tables - New persistent Tables API for contacts and companies, with an opt-in tableId parameter on Prospecting, Enrich, Signals, and Lookalike to save results directly into a table
See the Migration Guide for the full breakdown.