Skip to content
Changelog

Report a bug

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

See How connections work for access and permissions, or browse all integrations.