> ## Documentation Index > Fetch the complete documentation index at: https://docs.lusha.com/llms.txt > Use this file to discover all available pages before exploring further. # Lusha API - Frequently Asked Questions (Q&A) > Answers to common questions about Lusha's API endpoint groups, versioning, authentication, billing, rate limits, and errors. Lusha provides eight main 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, intent topics, 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 free previews. Pass the returned contact IDs to Enrich Contacts to reveal emails and phones. This replaces the retired Decision Makers API. **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. **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](/tutorials/v3-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. ```json theme={null} { "ids": ["4389064654", "4389064624"], "reveal": ["emails", "phones"], "waterfallEnabled": false } ``` 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, intent topics, 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), 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. 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. Pass `tableId` in the request body to also save matched results into an existing table and populate the Signals column. 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. This endpoint replaces the retired Decision Makers API. See the [Buying Group overview](/buying-group/overview). 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](/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: ```json theme={null} { "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 }] } ``` 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: | Code | Meaning | | ---- | ------------------------------------------------------------------ | | 200 | Success | | 400 | Bad request - malformed or missing parameters | | 401 | Unauthorized - invalid or missing API key | | 402 | Payment required - insufficient credits | | 403 | Forbidden - account inactive or feature not available on your plan | | 404 | Not found | | 409 | Conflict - a table with this name already exists | | 429 | Rate limit or daily quota exceeded | | 451 | Blocked due to GDPR regulations | | 5XX | Server error - retry with exponential backoff | Error response format: ```json theme={null} { "statusCode": 400, "message": "Invalid request parameters" } ``` Tables error bodies use a slightly different shape: `{ "message": "...", "code": , ... }`. 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 * **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](https://www.postman.com/lushateam/workspace/lusha-s-api/collection/28683568-fc849873-9ae1-47dd-8159-0d4deda04750) 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, intentTopics) 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`, `intent` * **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](/tutorials/v3-migration-guide) for the full breakdown.