Skip to content
Last updated

Lusha API - Frequently Asked Questions (Q&A)

Q: What APIs does Lusha offer?

A: Lusha provides six main RESTful API endpoint groups:

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

  2. Prospecting API Filter-based queries across Lusha's full database. Filter by job title, seniority, department, location, company size, revenue, industry, technologies, intent topics, and signals to build targeted contact and company lists. Returns up to 50,000 results per query (1,000 pages × 50 results).

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

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

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

  6. Website Visits API Identify and filter companies that have visited your website. Query traffic across your registered tracking sites and filter by engagement score, session depth, unique visitors, and geography to surface high-intent accounts. Returns company IDs you can pass directly to Enrich Companies for full firmographic data.

  7. Account API Returns current credit usage, rate limit status, plan details, and per-action pricing.

  8. Decision Makers API Identify the most relevant contacts to reach within a set of companies. Supply companies by domain or Lusha company ID and get back ranked decision makers as free previews (name, title, location, LinkedIn, seniority, department). Pass the returned contact IDs to Enrich Contacts to reveal emails and phones.

  9. Website Visits 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.

Q: What version of the API should I use?

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

Q: How do I make requests to Lusha's APIs?

A:

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

Q: How does authentication work?

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

Q: What is the search-then-enrich pattern in V3?

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

Q: What identifiers can I use to search for contacts?

A: Any one of the following per contact:

  • Lusha contact id
  • linkedinUrl
  • email
  • firstName + lastName + companyName or companyDomain

Up to 100 contacts per request.

Q: What identifiers can I use to search for companies?

A: Any one of the following per company:

  • Lusha company id
  • name
  • domain

Up to 100 companies per request.

Q: What does the Prospecting API do, and when should I use it?

A: 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, intent topics, funding, and signals.

Q: What filtering options are available in the Prospecting API?

A: 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), intent topics, 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.

Q: What is the Signals API, and how does it work?

A: The Signals API provides real-time market intelligence and activity data for contacts and companies.

Contact signals: promotion, companyChange

Company signals: headcount changes (1m/3m/6m/12m increase or decrease), surgeInHiring, surgeInHiringByDepartment, surgeInHiringByLocation, websiteTrafficIncrease, websiteTrafficDecrease, itSpendIncrease, itSpendDecrease, and 7 news signal categories: riskNews, commercialActivityNews, corporateStrategyNews, financialEventsNews, peopleNews, marketIntelligenceNews, productActivityNews.

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, and hiringByLocations to narrow results without separate requests.

Q: What is the Lookalikes API?

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

Q: What is the Website Visits API?

A: The Website Visits API (POST /v3/websiteVisits) returns a paginated list of companies that visited your website within a specified date range (max 3 months).

Each request requires at least one siteId — find yours by clicking the ⋯ menu next to a configured domain in the Lusha dashboard and selecting Copy Site ID.

Filter results by:

  • Engagement score band: cold, warm, or hot
  • Session metrics: totalSessions, uniqueVisitors, avgSessionMinutes, daysVisited, highIntentPageviews, daysSinceLastVisit
  • Geography: visitorCountries (include) and visitorCountriesExclude (exclude)

Sort by any metric field using sortBy and order. Paginate via limit (max 150) and offset. Results include a companyId you can pass directly to Enrich Companies for full firmographic data.

Q: What is the Website Visits API?

A: The Website Visits 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.

Q: What is the Website Visits API?

A: The Website Visits 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.

Q: What are Webhooks, and when should I use them?

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

Q: In what format are responses delivered?

A: All endpoints return JSON. Example V3 contact search response snippet:

{
  "id": "4415824633",
  "firstName": "Orit",
  "lastName": "Shilvock",
  "jobTitle": {
    "title": "Vice President of Partnerships",
    "departments": ["Business Development"],
    "seniority": "Vice President"
  },
  "has": ["firstName", "lastName", "jobTitle", "emails"],
  "canReveal": [{ "field": "emails", "credits": 1 }]
}

Q: Are there rate limits?

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

Q: How are API errors handled?

A: Lusha uses standard HTTP status codes. Common ones:

CodeMeaning
200Success
400Bad request - malformed or missing parameters
401Unauthorized - invalid or missing API key
402Payment required - insufficient credits
403Forbidden - account inactive or feature not available on your plan
404Not found
429Rate limit or daily quota exceeded
451Blocked due to GDPR regulations
5XXServer error - retry with exponential backoff

Error response format:

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

Q: How does credit billing work?

A: 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, intent) are charged separately per result
  • Signals: charged per matched signal per result
  • Lookalikes: charged per result returned
  • 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.

Q: Can I test the API before integrating?

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

Q: Where can I find valid filter values for Prospecting?

A: 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, intentTopics)

Some filters require a query parameter (e.g. locations, technologies, names).

Q: What's the difference between V2 and V3?

A: 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, intent
  • Signals are optional per-request - maxResultsPerSignal is now optional (previously required in v2.1.0)

See the Migration Guide for the full breakdown.

Previous page
Next page
Terms
Copyright © Lusha. All rights reserved.