Lusha integration: operations for AI agents
Lusha connects to Type.com as an integration. This page lists the 112 operations documented for Claude and Codex in Type.com: 83 read, 15 write, 14 destructive.
About Lusha
Lusha vendor API references, subject to account permissions.
Categories: Sales & CRM
How to connect Lusha to Type.com
- Access
- Organization connection: one shared account for the workspace.
To add the connection, follow the steps in Space connections.
Documented operations
112 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.
112 operations listed.
- Read
Search Contacts
Look up contacts by identifier. Returns a non-PII preview of each profile - no emails or phone numbers. **Accepted identifiers (one required per contact):** - Lusha contact `id` - `linkedinUrl` - `email` - `firstName` + `lastName` + `companyName` or `companyDomain` Up to 100 contacts per request. Each result includes: - `has` - data points available on this profile - `canReveal` - what you can unlock via Enrich Contacts, and the credit cost Pass a `signals` filter to narrow results to contacts with recent activity (e.g. promotion, job change). > **Billing:** Charged per successful result via the `api_search` action.
POST /v3/contacts/search - Read
Enrich Contacts
Reveal full contact data for contacts you've already found via Search Contacts. Pass up to 100 contact `ids` (from the search response). Use the `reveal` field to control what gets unlocked: - `emails` - work and personal email addresses - `phones` - mobile and direct phone numbers - Omit `reveal` to get both by default --- ### Waterfall Reveal Fall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts. If **Data Waterfall** is enabled on your account, with specific providers turned on under **Account > Waterfall**, 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: ```json "reveal": ["emails", "phones"], "waterfallEnabled": false ``` - `reveal` controls **which fields** come back. - `waterfallEnabled` controls whether the waterfall runs for this call at all. Defaults to `true` whenever Data Waterfall is enabled on your account; pass `false` to disable it just for this call. - Provider order isn't configurable - Lusha manages that internally. - If Data Waterfall is off or no providers are enabled on your account, `waterfallEnabled` has no effect either way. When the waterfall runs, the response adds `status`, `statusDescription` and (when a field is empty because the waterfall did not run) `statusReason`. Each email and phone carries `dataSource` (`lusha` or `<providerId>`), plus `credits` when an external provider delivered it. Contacts with unresolved data points list them in `missingDataPoints`. These fields are omitted when the waterfall did not run, so a Lusha-only response keeps its usual shape. ### Async results (`job`) Fast providers answer inside this call. A slower provider does not hold the request open: the response returns what is already known, plus a `job`. 1. If the response has no `job`, it is final. 2. If `job` is present, wait `job.retryAfter` seconds, then call [Get Contacts Enrich Job](#operation/getContactsEnrichJob) with `job.id`. 3. While the job `status` is `processing`, wait `retryAfter` seconds and poll again. 4. On `complete`, merge the job's `contacts` into your enrich results by `id`. Do not replace the whole enrich payload. 5. On `expired` or `failed`, stop and keep what Enrich Contacts already returned. Branch on whether `job` is present, and then on the job `status`. Don't infer that work is still running because an email or phone is empty. Polling is free. A data point is billed once, by whichever call delivered it. --- > **Tip:** If `canReveal.credits` is `0` in the search response, that data has already been revealed for your account - re-enriching it is free. > **Billing:** Charged per revealed field (email or phone) via per-datapoint pricing. > **Persisting to a table:** Pass `tableId` to also add these contacts to an existing table and populate the Work email / Phone columns. See [Contacts Tables](#tag/Contacts-Tables).
POST /v3/contacts/enrich - Read
Search and Enrich Contacts
Find contacts and reveal their full data in a single call. Combines Search and Enrich into one request. Provide contact identifiers the same way you would for Search Contacts. Use the `reveal` field to control what gets unlocked (`emails`, `phones`, or both). Up to 100 contacts per request. > **Billing:** Two charges apply - one for the search (`api_search`) and one per revealed field. The `billing.creditsCharged` in the response reflects the total. > **Data Waterfall:** runs automatically for the requested `reveal` fields when enabled on your account. There is no `waterfallEnabled` flag on this request. The response can include the same `status`, `statusDescription` and `statusReason` values as Enrich Contacts, plus `dataSource`, `credits` and `missingDataPoints`. It never returns a `job`, so there is nothing to poll.
POST /v3/contacts/search-and-enrich - Read
Search Companies
Look up companies by identifier. Returns a preview of each company profile. **Accepted identifiers (at least one required per company):** - Lusha company `id` - `name` - `domain` Up to 100 companies per request. Each result includes a `has` field listing the data available via Enrich Companies. Pass a `signals` filter to narrow results to companies showing specific activity (e.g. headcount growth, hiring surge). > **Billing:** Charged per successful result via the `api_search` action.
POST /v3/companies/search - Read
Enrich Companies
Reveal full company data for companies you've already found via Search Companies. Pass up to 100 company `ids` (from the search response). Each enriched result includes: - Firmographics: size, revenue range, year founded, company type - Industry: primary industry, sub-industry, SIC/NAICS codes - Locations: HQ and additional office sites - Technologies, funding rounds, buyer intent topics - LinkedIn followers, logo URL, social links (LinkedIn, Facebook, X, Instagram, YouTube, TikTok) - Open job posting counts: total and breakdowns by department, location, and seniority - Ownership: immediate parent (`directParent`) and top of the ownership tree (`ultimateParent`) > **Billing:** Charged per successful result via the `reveal_company` action. > **Persisting to a table:** Pass `tableId` to also add these companies to an existing table and populate the relevant enrichment columns. See [Companies Tables](#tag/Companies-Tables).
POST /v3/companies/enrich - Read
Search and Enrich Companies
Find companies and reveal their full data in a single call. Combines Search and Enrich into one request. Provide company identifiers the same way you would for Search Companies. Up to 100 companies per request. Use the `reveal` field to control which premium data points are unlocked, exactly as you would on Enrich Companies. Premium fields - including `directParent` and `ultimateParent` - are returned only when you name them in `reveal`; they are never included by default. > **Billing:** Same as Enrich Companies - charged per successful result via the `reveal_company` action, plus one charge per revealed field.
POST /v3/companies/search-and-enrich - Read
Prospecting Contacts
Search for contacts that match your Ideal Customer Profile using rich filter criteria. **Filter by contact attributes:** - Job title, seniority, department - Location (city, state, country, continent) - Existing data points (e.g. only contacts with a known work email) - Signal activity (promotion, job change) **Filter by company attributes:** - Size, revenue, industry, technologies - Location, intent topics, funding Use `options.maxContactsPerCompany` (1–20) to cap how many contacts are returned per company; `pagination.size` still controls the page size. Use the returned contact `id` values with Enrich Contacts to reveal emails and phones. > **Billing:** Charged per result via `api_search`. If signals are requested, an additional charge applies per matched signal per result. > **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. This is additive - the primary response is unchanged, and a `tableWrite` object is added showing what happened on the table side. See [Contacts Tables](#tag/Contacts-Tables).
POST /v3/contacts/prospecting - Read
Prospecting Companies
Search for companies that match your target market using rich filter criteria. **Filter by:** - Size, revenue range, industry, sub-industry - Technologies in use - Locations (HQ country, state, city) - SIC and NAICS codes - Buyer intent topics - Signal activity (headcount changes, hiring surges, news events, LinkedIn activity intent) Use the returned company `id` values with Enrich Companies to get full firmographic data. > **Billing:** Charged per result via `api_search`. If signals are requested, an additional charge applies per matched signal per result. > **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. This is additive - the primary response is unchanged, and a `tableWrite` object is added showing what happened on the table side. See [Companies Tables](#tag/Companies-Tables).
POST /v3/companies/prospecting - Read
Contact Lookalikes
Find contacts similar to a set of seed contacts using AI-powered recommendations. Provide seed contacts via LinkedIn URLs, emails, Lusha IDs, or name + company. The API returns contacts who share similar roles, seniority, and company profiles. > **Required: 5–100 seeds.** `seeds` must contain **at least 5** and **at most 100** contacts in total, counted across *all* identifier types combined (`linkedinUrls` + `emails` + `ids` + `contactIds` + `contacts`). A request with fewer than 5 total seeds is rejected with `400`. Fewer than 5 seeds does not give the model enough signal to produce useful lookalikes. **Pagination without duplicates:** On your first request, omit `dedupeSessionId` - the server generates one and returns it. Pass it on every subsequent request to get more results without repeating contacts already seen. Sessions are retained for 30 days. Use the `exclude` field to always filter out specific contacts (e.g. existing customers). Results are lightweight previews. Use Enrich Contacts with the returned `id` to get emails and phones. > **Billing:** Charged per result via the `lookalikeContact` action. > **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables).
POST /v3/contacts/lookalike - Read
Company Lookalikes
Find companies similar to a set of seed companies using AI-powered recommendations. Provide seed companies via domains or LinkedIn URLs. The API returns companies with similar size, industry, and profile. > **Required: 5–100 seeds.** `seeds` must contain **at least 5** and **at most 100** companies in total, counted across *all* identifier types combined (`domains` + `linkedinUrls`). A request with fewer than 5 total seeds is rejected with `400`. **Pagination without duplicates:** On your first request, omit `dedupeSessionId` - the server generates one and returns it. Pass it on every subsequent request to get more results without repeating companies already seen. Sessions are retained for 30 days. Use the `exclude` field to always filter out specific companies (e.g. existing customers or competitors). Results are lightweight previews. Use Enrich Companies with the returned `id` to get full firmographic data. > **Billing:** Charged per result via the `lookalikeCompany` action. > **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. See [Companies Tables](#tag/Companies-Tables).
POST /v3/companies/lookalike - Read
Contact Recommendations
Returns the recommended contacts for the calling user, ranked by Lusha against your Target Profiles and recent signals. Each result is a contact preview (name, job title, company, location, LinkedIn URL) plus a `recommendation` block with the lead score, ICP fit score, signal score, and the Target Profiles it matches. All scores are between `0` and `1`. Emails and phones are not included. Pass the returned `id` to [Enrich Contacts](#operation/enrichContacts) to reveal them. **Filtering:** Get valid `targetIcp` ids and `signals` names from [Contact Recommendation Filters](#operation/getContactRecommendationFilters). Values within the same filter are OR-ed. **Sorting:** Up to 4 sort entries from `leadScore`, `signalScore`, `icpFitScore`, and `targetIcp`, applied in order. All entries must use the same `order`; mixing `asc` and `desc` returns `400`. The default is `leadScore` descending. **Pagination:** `page` is 0-based (0-1000), `size` is 10-100. The defaults are `page: 0` and `size: 25`. An empty body `{}` returns the first 25 recommendations. > **Access:** Requires a user-scoped identity, either OAuth or an API key owned by a team member. Account-wide API keys return `403`. > **Billing:** Charged per result without an `error`, via the `contactRecommendationsReveal` action. Results with an `error` (e.g. `COMPLIANCE_RESTRICTED`) keep their scores but carry no personal data and are not charged.
POST /v3/contacts/recommendations - Read
Company Recommendations
Returns the recommended companies for the calling user, ranked by Lusha against your Target Profiles and recent signals. Each result is a company preview (name, domain, size, industry, location, LinkedIn URL) plus a `recommendation` block with the lead score, ICP fit score, signal score, the Target Profiles it matches, and intent topics when available. All scores are between `0` and `1`. Pass the returned `id` to [Enrich Companies](#operation/enrichCompanies) for full firmographic data. **Filtering:** Get valid `targetIcp` ids and `signals` names from [Company Recommendation Filters](#operation/getCompanyRecommendationFilters). Values within the same filter are OR-ed. **Sorting:** Up to 4 sort entries from `leadScore`, `signalScore`, `icpFitScore`, and `targetIcp`, applied in order. All entries must use the same `order`; mixing `asc` and `desc` returns `400`. The default is `leadScore` descending. **Pagination:** `page` is 0-based (0-1000), `size` is 10-100. The defaults are `page: 0` and `size: 25`. An empty body `{}` returns the first 25 recommendations. > **Access:** Requires a user-scoped identity, either OAuth or an API key owned by a team member. Account-wide API keys return `403`. > **Billing:** Charged per result without an `error`, via the `companyRecommendationsReveal` action.
POST /v3/companies/recommendations - Read
Contact Recommendation Filters
Lists the Target Profiles and signal types that currently appear in your contact recommendations. Pass these values to `filters.targetIcp` and `filters.signals` of [Contact Recommendations](#operation/getContactRecommendations). > **Access:** Requires a user-scoped identity, either OAuth or an API key owned by a team member. Account-wide API keys return `403`. > **Billing:** Free.
GET /v3/contacts/recommendations/filters - Read
Company Recommendation Filters
Lists the Target Profiles and signal types that currently appear in your company recommendations. Pass these values to `filters.targetIcp` and `filters.signals` of [Company Recommendations](#operation/getCompanyRecommendations). > **Access:** Requires a user-scoped identity, either OAuth or an API key owned by a team member. Account-wide API keys return `403`. > **Billing:** Free.
GET /v3/companies/recommendations/filters - Read
Get Buying Group Contacts
Identify the buying group within a set of target companies. Supply companies by `domain` or Lusha company `id` - the model scores and labels each returned contact with a persona role. **Personas:** - `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 Pass `personas` to filter to specific roles, or omit it to get all three. Use `contactsLimit` to cap how many contacts are returned per company (default 60). Results are lightweight previews grouped by company. Each contact includes a `has` field listing available data points, a `canReveal` field showing what can be unlocked via Enrich, a `roles` array with the assigned persona(s), and a `score` (0-1) reflecting relevance to the assigned role. Use Enrich Contacts with the returned contact `id` to reveal emails and phones. > **Billing:** Charged per contact returned via the `buyingGroupContact` action.
POST /v3/contacts/buying-group - Read
List Contacts Tables
List contacts tables owned by the given user, plus any tables shared with the account. > **Billing:** Free.
POST /v3/contacts/tables/list - Read
Get Contacts Column Catalog
List every Lusha data column that can be added to a contacts table - 22 columns. No request body and no parameters. Each entry returns the column's `category`, `displayName` (e.g. "Job title"), `columnKey` (e.g. `jobTitle` - the key you pass to [Add Columns to Contacts Table](#operation/addContactsTableColumns)), and `type` (`string` / `number` / `object`). > **Not the same as** [List Contacts Table Columns](#operation/listContactsTableColumns). > That endpoint lists the columns a *specific table already has*; this one lists > what's *available to add*. > **Billing:** Free - no credits charged.
GET /v3/contacts/tables/columns - Read
Get Contacts Table
Get a table's metadata and current processing status. > **Billing:** Free.
GET /v3/contacts/tables/{table_id} - Read
Get Contacts Table Entities
Read a page of rows in the table, with all column values and per-cell status. > **Billing:** Charged per row returned via `export_api`.
GET /v3/contacts/tables/{table_id}/entities - Read
List Contacts Table Columns
List the columns on a table, with type and aggregated per-cell status counts. > **Billing:** Free.
GET /v3/contacts/tables/{table_id}/columns - Read
List Companies Tables
List companies tables owned by the given user, plus any tables shared with the account. > **Billing:** Free.
POST /v3/companies/tables/list - Read
Get Companies Column Catalog
List every Lusha data column that can be added to a companies table - 46 columns. No request body and no parameters. Each entry returns the column's `category`, `displayName` (e.g. "Industry"), `columnKey` (e.g. `industry` - the key you pass to [Add Columns to Companies Table](#operation/addCompaniesTableColumns)), and `type` (`string` / `number` / `object`). > **Not the same as** [List Companies Table Columns](#operation/listCompaniesTableColumns). > That endpoint lists the columns a *specific table already has*; this one lists > what's *available to add*. > **Billing:** Free - no credits charged.
GET /v3/companies/tables/columns - Read
Get Companies Table
Get a table's metadata and current processing status. > **Billing:** Free.
GET /v3/companies/tables/{table_id} - Read
Get Companies Table Entities
Read a page of rows in the table, with all column values and per-cell status. > **Billing:** Charged per row returned via `export_api`.
GET /v3/companies/tables/{table_id}/entities - Read
List Companies Table Columns
List the columns on a table, with type and aggregated per-cell status counts. > **Billing:** Free.
GET /v3/companies/tables/{table_id}/columns - Read
Contact Signals
Retrieve signal events for a list of contacts - job changes and promotions. Pass up to 100 contact `ids`. Use `signalTypes` to specify which events to return (`promotion`, `companyChange`, or `allSignals`). Optionally set a `startDate` to limit results to recent activity. > **Billing:** Charged per matched signal per result via the `showSignalsContact` action. > **Persisting to a table:** Pass `tableId` to also add these contacts to an existing table and populate the Signals column. See [Contacts Tables](#tag/Contacts-Tables).
POST /v3/contacts/signals - Read
Company Signals
Retrieve signal events for a list of companies - hiring activity, headcount changes, web traffic, IT spend, news, and intent. Pass up to 100 company `ids`. Use `signalTypes` to specify which signals to return (or use `allSignals`). Optionally set a `startDate` to limit results to recent activity. ### Intent signals Four signal types track week-over-week changes in what a company is researching: - `newIntentTopic` - a topic with no activity the previous week now has a score - `intentScoreIncrease` - the topic's score went up compared to the previous week - `intentScoreDecrease` - the topic's score went down compared to the previous week - `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. `allSignals` does **not** include the intent types - name them in `signalTypes`. Narrow them with `filters.include.intentTopics` (find exact names with [Get Company Signal Filter Values](#operation/getCompanySignalFilterValues) and `filterType=intentTopics`) and `filters.include.intentCategories`. Every topic in the catalog is available - the topics selected in your dashboard don't apply. > **Billing:** Charged per matched signal per result via the `showSignalsCompany` action. Intent signals are charged the same way as every other company signal - no matches, no charge. > **Persisting to a table:** Pass `tableId` to also add these companies to an existing table and populate the Signals column. See [Companies Tables](#tag/Companies-Tables).
POST /v3/companies/signals - Read
Get Contact Signal Types
Returns the full list of supported signal types for contacts.
GET /v3/contacts/signals/types - Read
Get Company Signal Types
Returns the full list of supported signal types for companies.
GET /v3/companies/signals/types - Read
Get Company Signal Filters (Discovery)
Returns all available filter types for company signals and whether each requires a search query.
GET /v3/companies/signals/filters - Read
Get Company Signal Filter Values
Returns valid values for a single company signal filter type. | Filter type | Query required? | |---|---| | `newsEventTypes` | No | | `hiringByDepartments` | No | | `hiringByLocations` | Yes (2-256 chars) | | `intentCategories` | No - the `query` parameter is not supported for this filter type; passing one returns `400` | | `intentTopics` | Yes (2-256 chars) | `intentTopics` is a text search over the full intent topic catalog (about 18,000 topics). It returns up to 50 matching topic names as plain strings - pass them as `filters.include.intentTopics` on [Company Signals](#operation/getCompanySignals). No match returns `200` with an empty `values` list. > **Billing:** Free.
GET /v3/companies/signals/filters/{filterType} - Read
Score Companies by Signal Activity
Score companies by their active buying signals. Returns the aggregate Signal Score - a `[0, 1]` value reflecting the fraction of the company's active signals - plus the active signal breakdown. Accepts up to 100 companies, each identified by exactly one of `id`, `domain`, `name`, or `email`. All identifiers are resolved to Lusha company IDs server-side before scoring. Each result is one of: - A **scored entry** - `signalScore`, `signalTypes`, and `noActiveSignals`. - A **`NOT_FOUND`** entry - the company service could not resolve the supplied identifier. - A **`NO_SCORE`** entry - the company resolved, but the scoring engine returned nothing for it. > **Billing:** 1 credit is charged per scored row via `signal_score_company_reveal`. This action is currently limited-availability - while it isn't yet seeded on an account's pricebook, the endpoint stays free (`billing.creditsCharged` is `0`). Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.
POST /v3/companies/signal-score - Read
Score Contacts by Signal Activity
Score contacts by their active buying signals. Returns the aggregate Signal Score - a `[0, 1]` value - plus the active signal breakdown per contact. Accepts up to 100 contacts. Each contact is resolved to a Lusha person ID and company ID server-side (identity only - no PII is revealed) before scoring. Provide one of: - `id` (encrypted Lusha contact ID) - `linkedinUrl` - `email` - `firstName` + `lastName` + (`companyName` or `companyDomain`) Each result is one of: - A **scored entry** - `signalScore`, `signalTypes`, and `noActiveSignals`. - A **`NOT_FOUND`** entry - identity resolution failed for the supplied identifier. - A **`NO_SCORE`** entry - the contact resolved, but the scoring engine returned nothing for it. > **Note:** A full outage of the identity-resolution provider is never masked as `NOT_FOUND` - it returns a retryable `502` instead, so callers can retry rather than treating the batch as authoritatively unresolved. > **Billing:** 1 credit is charged per scored row via `signal_score_contact_reveal`. This action is currently limited-availability - while it isn't yet seeded on an account's pricebook, the endpoint stays free (`billing.creditsCharged` is `0`). Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.
POST /v3/contacts/signal-score - Read
List Target Profiles
Returns the Target Profiles (ICPs) you can see: your own, plus any an admin has shared with the account. Use the returned `id` values as `targetProfileIds` on [Score Companies by ICP Fit](#operation/getCompanyIcpFitScores) and [Score Contacts by ICP Fit](#operation/getContactIcpFitScores). Only `active` profiles can be used for scoring. > **Billing:** Free (0 credits).
GET /v3/icp/profiles - Read
Score Companies by ICP Fit
Score how well each company fits 1-3 of your Target Profiles, from `0` to `1`. Accepts 1-100 companies, each identified by exactly one of `id`, `domain`, `name`, or `email`, plus an optional `clientReferenceId`. `targetProfileIds` must be active profiles you own or that are shared with your account - get them from [List Target Profiles](#operation/listIcpProfiles). Each result is one of: - A **scored entry** - `icpFitScore` (the best fit), `topProfile` (the profile it fits best), and `profileScores` (the score per profile, only when more than one profile is requested). - A **`NOT_FOUND`** entry - the supplied identifier could not be resolved to a company. - A **`NO_SCORE`** entry - the company resolved, but no ICP fit score is available for it. > **Billing:** 1 credit per scored company, regardless of how many profiles it's scored against. A score of `0` is charged. Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.
POST /v3/companies/icp-fit-score - Read
Score Contacts by ICP Fit
Score how well each contact fits 1-3 of your Target Profiles, from `0` to `1`. Accepts 1-100 contacts, each identified by one of `id`, `linkedinUrl`, `email`, or `firstName` + `lastName` + (`companyName` | `companyDomain`), plus an optional `clientReferenceId`. `targetProfileIds` must be active profiles you own or that are shared with your account - get them from [List Target Profiles](#operation/listIcpProfiles). Each result is one of: - A **scored entry** - `fullName`, `company` (`id`, `name`, `domain`), `icpFitScore` (the best fit), `topProfile` (the profile it fits best), and `profileScores` (the score per profile, only when more than one profile is requested). - A **`NOT_FOUND`** entry - the supplied identifier could not be resolved to a contact. - A **`NO_SCORE`** entry - the contact resolved, but no ICP fit score is available for it. > **Billing:** 1 credit per scored contact, regardless of how many profiles it's scored against. A score of `0` is charged. Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.
POST /v3/contacts/icp-fit-score - Read
Get Website Visitors
Returns companies ranked by website-visit signals for your tracked domains and date range. Domains must be configured for tracking in the Lusha dashboard - they are resolved to site IDs server-side. Each result combines a V3 company firmographic preview (same shape as Search Companies) with behavioral visit metrics. **Notes:** - Date range must be ≤ 3 months - If any requested domain is not configured for tracking, the entire request fails with `400` - `limit` accepts 1–150
POST /v3/companies/website-visits - Read
Get Contact Filter Types (Discovery)
Returns all available filter types for contact prospecting and whether each requires a search query.
GET /v3/contacts/prospecting/filters - Read
Get Contact Filter Values
Returns valid values for a single contact filter type. | Filter type | Query required? | |---|---| | `departments` | No | | `seniority` | No | | `existingDataPoints` | No | | `countries` | No | | `locations` | Yes (2-256 chars) |
GET /v3/contacts/prospecting/filters/{filterType} - Read
Get Company Filter Types (Discovery)
Returns all available filter types for company prospecting and whether each requires a search query.
GET /v3/companies/prospecting/filters - Read
Get Company Filter Values
Returns valid values for a single company filter type. | Filter type | Query required? | |---|---| | `sizes` | No | | `revenues` | No | | `sics` | No | | `naics` | No | | `intentTopics` | No - the `query` parameter is not supported for this filter type; passing one returns `400` | | `industriesLabels` | No | | `names` | Yes (2-256 chars) | | `technologies` | Yes (2-256 chars) | | `locations` | Yes (2-256 chars) |
GET /v3/companies/prospecting/filters/{filterType} - Read
List Subscriptions
Returns all webhook subscriptions for your account with pagination support. *Endpoint*: **(GET) https://api.lusha.com/api/subscriptions** **Pagination:** - Results are sorted by `createdAt` in descending order (newest first) - Default limit: 10, max limit: 100 - Use `offset` for pagination through large result sets > **Note:** The webhook `secret` is never returned in list responses for security.
GET /api/subscriptions - Read
Get Subscription by ID
Returns a single webhook subscription by ID. *Endpoint*: **(GET) https://api.lusha.com/api/subscriptions/{id}**
GET /api/subscriptions/{id} - Read
Get Audit Logs
Retrieve webhook delivery logs for your account. *Endpoint*: **(GET) https://api.lusha.com/api/audit-logs** **What's Logged:** - All webhook delivery attempts (success and failures) - HTTP status codes and response times - Error messages for failed deliveries - Delivery timestamps and duration metrics **Filtering:** - Filter by subscription ID to see logs for specific subscriptions - Filter by status to see only successes, failures, or permanent failures **Rate Limit:** 100 requests/minute per account > **Note:** Logs are retained for 90 days (successful) and 180 days (failed/DLQ)
GET /api/audit-logs - Read
Get Audit Log Statistics
Get delivery statistics for your account. *Endpoint*: **(GET) https://api.lusha.com/api/audit-logs/stats**
GET /api/audit-logs/stats - Read
Get Account Secret
Retrieve the current account webhook secret. *Endpoint*: **(GET) https://api.lusha.com/api/account/secret**
GET /api/account/secret - Read
Get Account Usage
Returns a full snapshot of your account status: - **Credits** - total, used, and remaining for the current billing cycle - **Rate limits** - current usage and reset times for daily, hourly, and per-minute windows - **Plan** - your current plan category and renewal dates - **Pricing** - credit cost per action type across all public API endpoints > **Rate limit:** This endpoint is limited to 5 requests per minute.
GET /v3/account/usage - Read
Search Conversations
Search the sales conversations recorded by Lusha Conversations for your account. Returns each conversation's metadata, AI summary, action items, risks, objections, competitor mentions, coaching analysis, and chapters. Transcripts are not included - fetch those from [Get Conversation Transcript](#operation/getConversationTranscript). **Two modes on the same contract:** - **Keyword mode** - supply `query` to rank conversations by transcript content. All other filters are ignored. - **Filter mode** - omit `query` and supply the structural filters. Both modes return the same response shape. An empty body is valid and returns the first page of the account's conversations. **Validation notes:** - `companyDomains` matches on domain, not display name. Resolve a company name to a domain first (e.g. via [Search Companies](#operation/searchCompanies)). - `dateFrom` / `dateTo` accept date-only `YYYY-MM-DD` values. Datetimes, reduced precision (`2026`, `2026-01`), basic format (`20260101`), and impossible dates (`2026-02-31`) are rejected with `400`. - `pageSize` above 100 is rejected with `400` - it is not silently clamped. - `conversationIds` that don't exist, are still processing, or belong to another account are omitted from the response rather than erroring. > **Billing:** 1 credit per block of up to 25 conversations returned (1–25 = 1, 26–50 = 2, 51–75 = 3, 76–100 = 4), via `ci_meeting_data_export`. Charged on results returned, not the page size requested. A request that returns nothing is free. While `ci_meeting_data_export` isn't seeded on your account's pricebook, the endpoint stays free (`billing.creditsCharged` is `0`). > **Note:** `summary`, `coaching`, and `chapters` come from an asynchronous post-call pipeline. A `null` summary on a recent conversation means analysis isn't ready yet, not "nothing found". A `null` `severity` on a risk or objection means the pipeline didn't assess it - do not read it as "low".
POST /v3/account/conversations/search - Read
Get Conversation Transcript
Returns the speaker-attributed, timestamped transcript of a single conversation. Get the `conversationId` from [Search Conversations](#operation/searchConversations). No request body and no query parameters. > **Billing:** 1 credit per successful request via `ci_transcript_analysis`, including repeat requests for the same conversation. A `404` is never charged. While `ci_transcript_analysis` isn't seeded on your account's pricebook, the endpoint stays free. > **Note:** A single `404` covers all three cases - the conversation doesn't exist, its processing hasn't completed, or it belongs to another account. Transcripts can be long; when feeding one to an LLM, budget for it or summarize it (Search Conversations already returns the summary, chapters, and coaching without the transcript).
GET /v3/account/conversations/{conversationId}/transcript - Read
Get Contacts Enrich Job
Poll the async Data Waterfall job returned in the `job` field of [Enrich Contacts](#operation/enrichContacts). No body and no query parameters. - While `status` is `processing`, wait `retryAfter` seconds and poll again. `covers` lists what is still outstanding. - On `complete`, merge `contacts` into your enrich results by `id`. The job returns only the contacts it was still working on - contacts already returned by Enrich Contacts are not repeated. - On `expired` or `failed`, stop and keep what Enrich Contacts already returned. > **Billing:** Polling does not charge credits. `creditsCharged` is the async charge only - Enrich Contacts already reported its own in `billing.creditsCharged`. > **Errors:** `404` means the job does not exist, has expired, or belongs to another account (these are not distinguished) - stop polling. `503` means the job store could not be reached - retry. A `503` does not mean the job is gone.
GET /v3/contacts/jobs/{jobId} - Read
Search Single Contact
Find and enrich a single contact using various search criteria. You can search by name, email, LinkedIn URL, or Person Id. >##### Endpoint ``` GET https://api.lusha.com/v2/person ``` >##### Search Requirements You must provide either: - `personId` OR - `email` OR - `linkedinUrl` OR - `firstName` AND `lastName` AND (`companyName` OR `companyDomain`) >##### Notes: - Provide as much information as possible for better results - Using `personId` provides the most direct way to retrieve contact information, as it uniquely identifies a contact in Lusha's database. - Use `refreshJobInfo=true` to get the latest employment data - Use `filterBy` parameter to specify what contact details you need - Include the `signals` parameter to retriever contact signals (If no signals data is found for the specified period, the `signals` object will be empty but still present in the response.) - When requesting signals, you can optionally specify a start date using `signalsStartDate`. - Signals data is optional. If you don't include the `signals` parameter, no signals data will be returned. --- ⚠️ **Important Notice - Unified Credits Plan Required** | Parameter | Requirement | |-----------|-------------| | `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan | | Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error | | Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available | ---
GET /v2/person - Read
Search Single Company
Find detailed information about a single company by using different paramaters. >##### Endpoint: ``` GET https://api.lusha.com/v2/company ``` >##### Notes: - At least one of `domain`, `company`, or `companyId` is required. - Signal sub-filters (`newsEventTypes`, `hiringByDepartments`, `hiringByLocations`) are not supported on this endpoint. Use `POST /bulk/company/v2` with the `signalsFilters` parameter for filtered signal retrieval.
GET /v2/company - Read
Departments
Get list of available departments for contact filtering
GET /prospecting/filters/contacts/departments - Read
Seniority
Get list of available seniority levels for contact filtering
GET /prospecting/filters/contacts/seniority - Read
Data Points
Get list of available data points for contact filtering
GET /prospecting/filters/contacts/existing_data_points - Read
Countries
Get list of all available countries for contact filtering
GET /prospecting/filters/contacts/all_countries - Read
Locations
Search for locations by text for contact filtering
POST /prospecting/filters/contacts/locations - Read
Names
Search for company names by text
POST /prospecting/filters/companies/names - Read
Industries
Get list of available industries for company filtering
GET /prospecting/filters/companies/industries_labels - Read
Sizes
Get list of available company size ranges
GET /prospecting/filters/companies/sizes - Read
Revenues
Get list of available revenue ranges
GET /prospecting/filters/companies/revenues - Read
Locations
Search for company locations by text
POST /prospecting/filters/companies/locations - Read
SIC Codes
Get list of available SIC codes
GET /prospecting/filters/companies/sics - Read
NAICS Codes
Get list of available NAICS codes
GET /prospecting/filters/companies/naics - Read
Intent Topics
Get list of available intent topics
GET /prospecting/filters/companies/intent_topics - Read
Technologies
Search for technologies by text
POST /prospecting/filters/companies/technologies - Read
Search Contacts
Search for contacts using various filters. This is step 2 of the prospecting process. *Endpoint*: **(POST) https://api.lusha.com/prospecting/contact/search** --- ##### Signal Filtering (Premium Feature) Filter contacts by signal types to find prospects at key career moments. > **Note:** This is a premium feature. Credits are charged for each signal type that returns results. --- ##### DNC Filtering (Scale Feature) Use `excludeDnc: true` at the top level of the request body to filter out contacts whose phone numbers are all marked Do Not Call. - Contacts with **at least one callable phone** appear in results - Only callable phones are shown — DNC phones are hidden - Contacts with **only DNC phones** are excluded entirely > **Note**: Returns **403** on unsupported plans.
POST /prospecting/contact/search - Read
Enrich Contacts
Enrich contacts from search results. This is step 3 of the prospecting process. *Endpoint*: **(POST) https://api.lusha.com/prospecting/contact/enrich** --- ⚠️ **Important Notice - Unified Credits Plan Required** | Parameter | Requirement | |-----------|-------------| | `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan | | Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error | | Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available | ---
POST /prospecting/contact/enrich - Read
Search Companies
Search for companies using various filters. This is step 2 of the prospecting process. *Endpoint*: **(POST) https://api.lusha.com/prospecting/company/search** --- ##### Signal Filtering (Premium Feature) Filter companies by signal types to identify those with recent business events and changes. > **Note:** This is a premium feature. Credits are charged for each signal type that returns results.
POST /prospecting/company/search - Read
Enrich Companies
Enrich companies from search results. This is step 3 of the prospecting process. *Endpoint*: **(POST) https://api.lusha.com/prospecting/company/enrich**
POST /prospecting/company/enrich - Read
Get Signal Options
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 <br /> **Hiring & Workforce:** * **`surgeInHiring`** - Overall hiring activity increase * **`surgeInHiringByDepartment`** - Department-specific hiring surges * **`surgeInHiringByLocation`** - Location-specific hiring surges <br /> **Headcount Trends:** | Signal | Description | |--------|-------------| | `headcountIncrease1m` / `headcountDecrease1m` | 1-month employee count changes | | `headcountIncrease3m` / `headcountDecrease3m` | 3-month employee count changes | | `headcountIncrease6m` / `headcountDecrease6m` | 6-month employee count changes | | `headcountIncrease12m` / `headcountDecrease12m` | 12-month employee count changes | <br /> **Technology & Digital Presence:** * **`websiteTrafficIncrease`** - Website traffic growth * **`websiteTrafficDecrease`** - Website traffic decline * **`itSpendIncrease`** - IT spending increase * **`itSpendDecrease`** - IT spending decrease **News Events:** To retrieve company news, use one or more of the following category values: | Signal | Included Events | |--------|-----------------| | `commercialActivityNews` | Partnership, New Customer, New Vendor | | `corporateStrategyNews` | M&A, Facilities Expansion, New Location, Facility Closure, Asset Sale, Lawsuit Filed | | `financialEventsNews` | Funding Round, Asset Investment, Strategic Investment, IPO | | `marketIntelligenceNews` | Event Participation, Recognition, Competitor Activity | | `peopleNews` | Executive Hire, Executive Departure, Executive Promotion, Headcount Increase, Headcount Decrease | | `productActivityNews` | Product Launch, Product Development, Product Integration | | `riskNews` | Security Issue, Lawsuit Faced | > The response also includes available values for signal sub-filters: * `newsEventTypes` — available event type values for news signal filtering * `hiringByDepartments` — available department values for hiring surge filtering * `hiringByLocations` — available location values for hiring surge filtering (array of `{ country, state }` objects)
GET /api/signals/filters/{objectType} - Read
Get Contact Signals by IDs
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
POST /api/signals/contacts - Read
Search Contact Signals
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
POST /api/signals/contacts/search - Read
Get Company Signals by IDs
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
POST /api/signals/companies - Read
Search Company Signals
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
POST /api/signals/companies/search - Read
Get Account Usage Statistics
Retrieve your current API credit usage statistics including used, remaining, and total credits. *Endpoint*: **(GET) https://api.lusha.com/account/usage** **Rate Limits**: This endpoint has a specific rate limit of 5 requests per minute.
GET /account/usage - Read
Contact Lookalikes (Legacy)
Returns contact lookalikes based on seed contacts. *Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/contacts** #### How It Works **First Request (Start a New Run):** - Do not send `dedupeSessionId` - Server generates one and returns it in the response - Use returned `dedupeSessionId` for subsequent "get more" requests **Subsequent Requests ("Get More"):** - Send the returned `dedupeSessionId` to fetch more results without duplicates - Server dedupes against all contacts previously returned for the `dedupeSessionId` - User-provided `exclude.*` is applied on every request and combined with server-side dedupe - Session history retained for 30 days from last activity (sliding window) ---
POST /v3/lookalike/contacts - Read
Company Lookalikes (Legacy)
Returns company lookalikes based on seed companies. *Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/companies** #### How It Works **First Request (Start a New Run):** - Do not send `dedupeSessionId` - Server generates one and returns it in the response - Use returned `dedupeSessionId` for subsequent "get more" requests **Subsequent Requests ("Get More"):** - Send the returned `dedupeSessionId` to fetch more results without duplicates - Server uses `dedupeSessionId` to deduplicate companies already returned - Session history retained for 30 days from last activity (sliding window) ---
POST /v3/lookalike/companies - Read
List Subscriptions (Legacy)
Returns all webhook subscriptions for your account with pagination support. *Endpoint*: **(GET) https://api.lusha.com/api/subscriptions** **Pagination:** - Results are sorted by `createdAt` in descending order (newest first) - Default limit: 10, max limit: 100 - Use `offset` for pagination through large result sets > **Note:** The webhook `secret` is never returned in list responses for security.
GET /api/subscriptions - Read
Get Subscription by ID (Legacy)
Returns a single webhook subscription by ID. *Endpoint*: **(GET) https://api.lusha.com/api/subscriptions/{id}**
GET /api/subscriptions/{id} - Read
Get Audit Logs (Legacy)
Retrieve webhook delivery logs for your account. *Endpoint*: **(GET) https://api.lusha.com/api/audit-logs** **What's Logged:** - All webhook delivery attempts (success and failures) - HTTP status codes and response times - Error messages for failed deliveries - Delivery timestamps and duration metrics **Filtering:** - Filter by subscription ID to see logs for specific subscriptions - Filter by status to see only successes, failures, or permanent failures **Rate Limit:** 100 requests/minute per account > **Note:** Logs are retained for 90 days (successful) and 180 days (failed/DLQ)
GET /api/audit-logs - Read
Get Audit Log Statistics (Legacy)
Get delivery statistics for your account. *Endpoint*: **(GET) https://api.lusha.com/api/audit-logs/stats**
GET /api/audit-logs/stats - Read
Get Account Secret (Legacy)
Retrieve the current account webhook secret. *Endpoint*: **(GET) https://api.lusha.com/api/account/secret**
GET /api/account/secret - Write
Create Contacts Table
Create a new, empty contacts table, optionally seeded with an initial list of contact IDs. > **Billing:** Free.
POST /v3/contacts/tables - Write
Add Entities to Contacts Table
Add up to 500 contact IDs to an existing table. `entityIds` accepts either the encrypted Lusha token (`v{N}.…`, as returned by Search/Enrich/Get Entities) or the legacy numeric `personId` - an ID that's neither returns `400`. Already-present IDs are reported as `alreadyPresent` and not re-added; unresolvable IDs are not an error, they come back in `invalidIds` with a `200`. Optionally pass `companyIds` - one `lushaCompanyId` per contact, index-aligned with `entityIds` - to help pair company-level enrichment to the right company for each contact. > **Billing:** Free.
POST /v3/contacts/tables/{table_id}/entities - Write
Add Columns to Contacts Table
Add up to 10 Lusha columns to a table in one call. Enrichment starts automatically on **all rows** in the table as soon as the columns are added. **Body** - either a list or a single key: - `columns: [{ "columnKey": "jobTitle" }, { "columnKey": "seniority" }]` - `columnKey: "jobTitle"` for a single column Keys come straight from [Get Contacts Column Catalog](#operation/getContactsColumnCatalog). **Partial success:** columns are handled independently. The response returns one entry per requested column with its own `status` (`added` / `failed`) and `columnId` - if one column fails the rest still go through. The most common failure is the column already being on the table, in which case the existing `columnId` is returned, so the call is safe to re-run. > **Billing:** Free today - credits aren't charged for adding columns yet.
POST /v3/contacts/tables/{table_id}/columns - Write
Run Column on Contacts Table
Populate or refresh a column's data for some or all rows in the table. This is **asynchronous** - the call returns immediately with `status: "processing"`; poll Get Contacts Table for `isProcessing` and per-column row-status counts to know when it's done, then read the values via Get Contacts Table Entities. **`runScope` values:** - `all` - every row, including already-processed ones (re-runs / refreshes). Most expensive. - `missing` - only rows that have never been run for this column. Cheapest, safe to call repeatedly. - `specific` - only the `entityIds` you pass. Also how you implement "run for this page" - fetch the page via Get Contacts Table Entities, then pass those IDs here. > **Billing:** Charged per row processed, per the column's credit tier. Re-running with `all` charges again for rows that already have data.
POST /v3/contacts/tables/{table_id}/columns/{column_id}/run - Write
Create Companies Table
Create a new, empty companies table, optionally seeded with an initial list of company IDs. > **Billing:** Free.
POST /v3/companies/tables - Write
Add Entities to Companies Table
Add up to 500 company IDs to an existing table. `entityIds` accepts either the encrypted Lusha token (`v{N}.…`, as returned by Search/Enrich/Get Entities) or the legacy numeric `lushaCompanyId` - an ID that's neither returns `400`. Already-present IDs are reported as `alreadyPresent` and not re-added; unresolvable IDs are not an error, they come back in `invalidIds` with a `200`. > **Billing:** Charges `reveal_company` per newly-added company, deduped via row-count delta - duplicates and already-present companies aren't charged again.
POST /v3/companies/tables/{table_id}/entities - Write
Add Columns to Companies Table
Add up to 10 Lusha columns to a table in one call. Enrichment starts automatically on **all rows** in the table as soon as the columns are added. **Body** - either a list or a single key: - `columns: [{ "columnKey": "industry" }, { "columnKey": "yearFounded" }]` - `columnKey: "industry"` for a single column Keys come straight from [Get Companies Column Catalog](#operation/getCompaniesColumnCatalog). **Partial success:** columns are handled independently. The response returns one entry per requested column with its own `status` (`added` / `failed`) and `columnId` - if one column fails the rest still go through. The most common failure is the column already being on the table, in which case the existing `columnId` is returned, so the call is safe to re-run. > **Billing:** Free today - credits aren't charged for adding columns yet.
POST /v3/companies/tables/{table_id}/columns - Write
Run Column on Companies Table
Populate or refresh a column's data for some or all rows in the table. This is **asynchronous** - the call returns immediately with `status: "processing"`; poll Get Companies Table for `isProcessing` and per-column row-status counts to know when it's done, then read the values via Get Companies Table Entities. **`runScope` values:** - `all` - every row, including already-processed ones (re-runs / refreshes). Most expensive. - `missing` - only rows that have never been run for this column. Cheapest, safe to call repeatedly. - `specific` - only the `entityIds` you pass. Also how you implement "run for this page" - fetch the page via Get Companies Table Entities, then pass those IDs here. > **Billing:** Charged per row processed, per the column's credit tier. Company enrichment charges once per company per table - re-runs on an already-paid company in the same table are free.
POST /v3/companies/tables/{table_id}/columns/{column_id}/run - Write
Create Subscription
Creates one or more webhook subscriptions for real-time signal notifications. **Delivery & Reliability:** - Webhooks are delivered with automatic retry on failures - Maximum 3 retry attempts with exponential backoff - Subscriptions auto-disable after max retries exceeded - All deliveries are logged in audit logs > **Note:** Your webhook endpoint must respond with a proper acknowledgment. See Client Response Format below for details. > **Limit:** Maximum 25 subscriptions per request *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions** --- ### Webhook Payload You'll Receive When a signal is triggered, this payload is sent to your webhook URL: ```json { "id": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c", "type": "promotion", "entityType": "contact", "entityId": "4158887495", "subscriptionId": "507f1f77bcf86cd799439011", "data": { "personId": 4158887495, "currentCompanyId": 40823133, "currentCompanyName": "OMG Hospitality Group LLC", "currentDomain": "omghospitalitygroup.com", "currentTitle": "Bartender", "currentDepartments": [ { "id": 7, "value": "Other" } ], "previousCompanyName": "First Watch Restaurants", "previousDomain": "firstwatch.com", "signalDate": "2025-07-01" }, "timestamp": "2026-01-14T16:16:35.841Z", "billing": { "creditsCharged": 1 } } ``` **Example - Company News Signal:** ```json { "id": "a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45", "type": "commercialActivityNews", "entityType": "company", "entityId": "33222678", "subscriptionId": "507f1f77bcf86cd799439011", "data": { "companyId": "33222678", "companyName": "Lusha", "domain": "lusha.com", "signalId": "1503910", "eventType": "partnership", "eventSummary": "Lusha announced a strategic partnership with Salesforce.", "articlePublishedDate": "2025-06-15", "articleTitle": "Lusha Partners with Salesforce", "articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.", "eventEffectiveDate": "2025-06-10", "articleUrl": "https://example.com/lusha-salesforce-partnership" }, "timestamp": "2026-01-14T16:16:35.841Z", "billing": { "creditsCharged": 1 } } ``` **Headers Included:** | Header | Description | |--------|-------------| | `X-Lusha-Signature` | HMAC-SHA256 signature for verification | | `X-Lusha-Timestamp` | Unix timestamp of the request | | `Content-Type` | application/json | | `User-Agent` | Lusha-Webhooks/1.0 | --- ⚠️ **Important:** Ensure your account has a webhook secret before creating subscriptions. Create one via the [Regenerate Account Secret](#operation/regenerateAccountSecret) endpoint. --- ### Client Response Format (Required) When your webhook endpoint receives a delivery, it **must** acknowledge receipt with this response: **Required Response:** ````json { "received": true, "timestamp": "2026-02-05T10:30:45.123Z", "webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c" } ```` <details> <summary><strong>Response Requirements</strong></summary> | Requirement | Value | |-------------|-------| | **HTTP Status** | `201 Created` (recommended) or any `2xx` status | | **Content-Type** | `application/json` | | **Response Time** | Within 10 seconds | </details> <details> <summary><strong>Field Descriptions & Implementation Guide</strong></summary> **Field Descriptions:** * `received` (boolean, required): Confirmation flag - must be `true` * `timestamp` (string, required): ISO 8601 timestamp of receipt * `webhookId` (string, required): Echo the `id` from webhook payload **Implementation Example:** ```javascript app.post('/webhook', async (req, res) => { // 1. Verify signature if (!verifyWebhookSignature(req)) { return res.status(401).json({ error: 'Invalid signature' }); } // 2. Queue for async processing await queueWebhook(req.body); // 3. Acknowledge immediately res.status(201).json({ received: true, timestamp: new Date().toISOString(), webhookId: req.body.id }); ``` **Important Notes:** * Return acknowledgment **before** heavy processing * Non-2xx responses trigger retry mechanism * After 3 failed retries, subscription is disabled </details> ----
POST /api/subscriptions - Write
Test Subscription
Test a webhook subscription by sending a test signal. Supports three test modes. *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/{id}/test** --- **Test Modes:** - `direct` - Quick HTTP check only (validates URL responds correctly) - `kafka` - Fanout handler only (tests Kafka message processing) - `full` - Complete Kafka flow (default - end-to-end test) **Important Notes:** - Test deliveries do NOT consume credits - Test payloads use mock data - Useful for verifying webhook configuration before going live
POST /api/subscriptions/{id}/test - Write
Create Opt-Out Subscription
Subscribe to real-time notifications when a contact opts out of data processing. When a contact requests removal, Lusha sends an `OptOutWebhookPayload` to your endpoint so you can action the removal in your own systems (CRM, outreach tools, etc.). *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/opt-out** --- **How it works:** - Create one opt-out subscription per account (scoped to `contact` entity type) - Lusha delivers a POST request to your URL whenever a contact opts out - The payload includes the contact identity, opt-out date, and the specific data points (emails and/or phones) that must be removed **Payload you'll receive:** ```json { "contactId": "987654321", "fullName": "Jane Doe", "companyName": "Acme Corp", "jobTitle": "Director of Product", "linkedinUrl": "https://www.linkedin.com/in/jane-doe", "contactOptOutDate": "2026-04-22 14:32:11.412", "contactExposureDate": "2025-08-03 09:15:47", "datapoints": [ { "datapointId": "+14155550199", "datapointType": "phone" }, { "datapointId": "jane.doe@acme.com", "datapointType": "email" } ], "partnerClientId": "acme-crm-tenant-42" } ``` > **Important:** Signature verification applies the same way as standard webhook deliveries. See [Security & Verification](#tag/Webhooks) for details. > **Note:** Ensure your account has a webhook secret before creating this subscription. See [Regenerate Account Secret](#operation/regenerateAccountSecret).
POST /api/subscriptions/opt-out - Write
Search Multiple Contacts
Enrich multiple contacts in a single request. This endpoint allows you to submit a list of contacts and receive enriched data for each one, including company information. >##### Endpoint: ``` POST https://api.lusha.com/v2/person ``` >##### Notes - You can process up to 100 contacts per request. - Using `personId` provides the most direct way to retrieve contact information. - At least one of `email`, `linkedinUrl`, or `company`/`domain` with `fullName` is required. --- ⚠️ **Important Notice - Unified Credits Plan Required** | Parameter | Requirement | |-----------|-------------| | `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan | | Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error | | Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available | ---
POST /v2/person - Write
Search Multiple Companies
Search for multiple companies in a single request. Provide a list of companies with identifiers like domain names or company IDs. >##### Endpoint: ``` POST https://api.lusha.com/bulk/company/v2 ``` >##### Notes: - At least one of `domain`, `company`, or `companyId` is required. - You can process up to 100 companies per request.
POST /bulk/company/v2 - Write
Create Subscription (Legacy)
Creates one or more webhook subscriptions for real-time signal notifications. **Delivery & Reliability:** - Webhooks are delivered with automatic retry on failures - Maximum 3 retry attempts with exponential backoff - Subscriptions auto-disable after max retries exceeded - All deliveries are logged in audit logs > **Note:** Your webhook endpoint must respond with a proper acknowledgment. See Client Response Format below for details. > **Limit:** Maximum 25 subscriptions per request *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions** --- ### Webhook Payload You'll Receive When a signal is triggered, this payload is sent to your webhook URL: ```json { "id": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c", "type": "promotion", "entityType": "contact", "entityId": "4158887495", "subscriptionId": "507f1f77bcf86cd799439011", "data": { "personId": 4158887495, "currentCompanyId": 40823133, "currentCompanyName": "OMG Hospitality Group LLC", "currentDomain": "omghospitalitygroup.com", "currentTitle": "Bartender", "currentDepartments": [ { "id": 7, "value": "Other" } ], "previousCompanyName": "First Watch Restaurants", "previousDomain": "firstwatch.com", "signalDate": "2025-07-01" }, "timestamp": "2026-01-14T16:16:35.841Z", "billing": { "creditsCharged": 1 } } ``` **Example — Company News Signal:** ```json { "id": "a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45", "type": "commercialActivityNews", "entityType": "company", "entityId": "33222678", "subscriptionId": "507f1f77bcf86cd799439011", "data": { "companyId": "33222678", "companyName": "Lusha", "domain": "lusha.com", "signalId": "1503910", "eventType": "partnership", "eventSummary": "Lusha announced a strategic partnership with Salesforce.", "articlePublishedDate": "2025-06-15", "articleTitle": "Lusha Partners with Salesforce", "articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.", "eventEffectiveDate": "2025-06-10", "articleUrl": "https://example.com/lusha-salesforce-partnership" }, "timestamp": "2026-01-14T16:16:35.841Z", "billing": { "creditsCharged": 1 } } ``` **Headers Included:** | Header | Description | |--------|-------------| | `X-Lusha-Signature` | HMAC-SHA256 signature for verification | | `X-Lusha-Timestamp` | Unix timestamp of the request | | `Content-Type` | application/json | | `User-Agent` | Lusha-Webhooks/1.0 | --- ⚠️ **Important:** Ensure your account has a webhook secret before creating subscriptions. Create one via the [Regenerate Account Secret](#operation/regenerateAccountSecret) endpoint. --- ### Client Response Format (Required) When your webhook endpoint receives a delivery, it **must** acknowledge receipt with this response: **Required Response:** ````json { "received": true, "timestamp": "2026-02-05T10:30:45.123Z", "webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c" } ```` <details> <summary><strong>Response Requirements</strong></summary> | Requirement | Value | |-------------|-------| | **HTTP Status** | `201 Created` (recommended) or any `2xx` status | | **Content-Type** | `application/json` | | **Response Time** | Within 10 seconds | </details> <details> <summary><strong>Field Descriptions & Implementation Guide</strong></summary> **Field Descriptions:** * `received` (boolean, required): Confirmation flag - must be `true` * `timestamp` (string, required): ISO 8601 timestamp of receipt * `webhookId` (string, required): Echo the `id` from webhook payload **Implementation Example:** ```javascript app.post('/webhook', async (req, res) => { // 1. Verify signature if (!verifyWebhookSignature(req)) { return res.status(401).json({ error: 'Invalid signature' }); } // 2. Queue for async processing await queueWebhook(req.body); // 3. Acknowledge immediately res.status(201).json({ received: true, timestamp: new Date().toISOString(), webhookId: req.body.id }); ``` **Important Notes:** * Return acknowledgment **before** heavy processing * Non-2xx responses trigger retry mechanism * After 3 failed retries, subscription is disabled </details> ----
POST /api/subscriptions - Write
Test Subscription (Legacy)
Test a webhook subscription by sending a test signal. Supports three test modes. *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/{id}/test** --- **Test Modes:** - `direct` - Quick HTTP check only (validates URL responds correctly) - `kafka` - Fanout handler only (tests Kafka message processing) - `full` - Complete Kafka flow (default - end-to-end test) **What Gets Tested:** - URL accessibility and response time - Complete delivery pipeline (for full mode) - Signature generation and headers **Important Notes:** - Test deliveries do NOT consume credits - Test payloads use mock data - Useful for verifying webhook configuration before going live
POST /api/subscriptions/{id}/test - Destructive
Update Contacts Table
Rename a table, change its visibility, or reassign its owner. All fields except `owner` are optional - send only what changes. > **Billing:** Free.
PATCH /v3/contacts/tables/{table_id} - Destructive
Delete Contacts Table
Permanently delete a table and all its data. This cannot be undone. > **Billing:** Free.
DELETE /v3/contacts/tables/{table_id} - Destructive
Remove Entities from Contacts Table
Remove specific contact IDs from a table. > **Billing:** Free.
DELETE /v3/contacts/tables/{table_id}/entities - Destructive
Remove Column from Contacts Table
Remove a column and delete all of its cell data across the table. Default Lusha columns cannot be removed. > **Billing:** Free.
DELETE /v3/contacts/tables/{table_id}/columns/{column_id} - Destructive
Update Companies Table
Rename a table, change its visibility, or reassign its owner. All fields except `owner` are optional - send only what changes. > **Billing:** Free.
PATCH /v3/companies/tables/{table_id} - Destructive
Delete Companies Table
Permanently delete a table and all its data. This cannot be undone. > **Billing:** Free.
DELETE /v3/companies/tables/{table_id} - Destructive
Remove Entities from Companies Table
Remove specific company IDs from a table. > **Billing:** Free.
DELETE /v3/companies/tables/{table_id}/entities - Destructive
Remove Column from Companies Table
Remove a column and delete all of its cell data across the table. Default Lusha columns cannot be removed. > **Billing:** Free.
DELETE /v3/companies/tables/{table_id}/columns/{column_id} - Destructive
Update Subscription
Updates an existing webhook subscription. All fields are optional. *Endpoint*: **(PATCH) https://api.lusha.com/api/subscriptions/{id}** --- **Reactivating Disabled Subscriptions:** When setting `isActive: true` on a previously disabled subscription, the system automatically: - Clears the `blockReason` field - Clears the `blockedAt` timestamp - Resets the retry counter **Regenerating Secrets:** Set `regenerateSecret: true` to generate a new webhook secret. The new secret: - Affects **all subscriptions** for your account - Is only shown once in the response - Immediately invalidates the old secret ---
PATCH /api/subscriptions/{id} - Destructive
Delete Subscriptions
Delete one or more webhook subscriptions. Returns detailed results for each deletion with partial success support. *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/delete** --- **Behavior:** - Each subscription is processed independently - Returns detailed results for each item including deleted subscription info - Invalid ID formats are gracefully handled and reported as NOT_FOUND - Duplicate IDs are automatically deduplicated - Deletion is permanent and cannot be undone
POST /api/subscriptions/delete - Destructive
Regenerate Account Secret
Regenerate the account webhook secret. Affects **all subscriptions** for the account. *Endpoint*: **(POST) https://api.lusha.com/api/account/secret/regenerate** **Behavior:** - If a secret already exists: Replaces with new secret (old secret is invalidated) - If no secret exists: Creates new secret automatically **Important Notes:** - The secret is only shown once in the response. Store it securely. - This endpoint always succeeds (upsert operation) - Regenerating invalidates the old secret for **all subscriptions** (if one existed) - An account secret must exist before webhooks can be delivered
POST /api/account/secret/regenerate - Destructive
Update Subscription (Legacy)
Updates an existing webhook subscription. All fields are optional. *Endpoint*: **(PATCH) https://api.lusha.com/api/subscriptions/{id}** --- **Reactivating Disabled Subscriptions:** When setting `isActive: true` on a previously disabled subscription, the system automatically: - Clears the `blockReason` field - Clears the `blockedAt` timestamp - Resets the retry counter **Regenerating Secrets:** Set `regenerateSecret: true` to generate a new webhook secret. The new secret: - Affects **all subscriptions** for your account - Is only shown once in the response - Immediately invalidates the old secret ---
PATCH /api/subscriptions/{id} - Destructive
Delete Subscriptions (Legacy)
Delete one or more webhook subscriptions. Returns detailed results for each deletion with partial success support. *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/delete** --- **Behavior:** - Each subscription is processed independently - Returns detailed results for each item including deleted subscription info - Invalid ID formats are gracefully handled and reported as NOT_FOUND - Duplicate IDs are automatically deduplicated - Deletion is permanent and cannot be undone
POST /api/subscriptions/delete - Destructive
Regenerate Account Secret (Legacy)
Regenerate the account webhook secret. Affects **all subscriptions** for the account. *Endpoint*: **(POST) https://api.lusha.com/api/account/secret/regenerate** **Behavior:** - If a secret already exists: Replaces with new secret (old secret is invalidated) - If no secret exists: Creates new secret automatically **Important Notes:** - The secret is only shown once in the response. Store it securely. - This endpoint always succeeds (upsert operation) - Regenerating invalidates the old secret for **all subscriptions** (if one existed) - An account secret must exist before webhooks can be delivered
POST /api/account/secret/regenerate
No operations match.
See How connections work for access and permissions, or browse all integrations.