{ "openapi": "3.0.3", "info": { "title": "Lusha API Documentation", "version": "", "x-logo": { "url": "https://www.lusha.com/logo.png" }, "license": { "name": "Proprietary", "url": "https://lusha.com/legal/terms" }, "description": "
\n\n **This is the Lusha API V3 documentation.** \n \n V3 introduces a new search-then-enrich pattern, bulk operations, AI-powered lookalikes, and richer filter capabilities. All endpoints are under `https://api.lusha.com/v3/`.\n\n For more information on V3, refer to the [Migration Guide](/tutorials/v3-migration-guide).\n\n
\n\n --- \n\nLusha provides a RESTful API for querying a comprehensive dataset of business profiles and company information. Built for teams running prospecting, enrichment, automation, and analytics workflows that need accurate, continuously updated business data. The API supports both real-time and bulk use cases.\n\nUse the Lusha API to **search for new prospects**, **enrich existing records**, **react to real-world changes**, and **expand coverage** with AI-powered lookalike recommendations.\n\n> All API requests must be made over **HTTPS**. All responses are returned in **JSON** format.\n\n--- \n## Available Endpoints\n\n| Category | Description |\n|---|---|\n| [**Search**](#tag/Search) | Find contacts or companies using known identifiers |\n| [**Enrich**](#tag/Enrich) | Retrieve full profile data for contacts or companies by ID |\n| [**Search & Enrich**](#tag/Search-and-Enrich) | Find and retrieve full contact or company data in a single call |\n| [**Prospecting**](#tag/Prospecting) | Filter-based search across contacts and companies |\n| [**Lookalikes**](#tag/Lookalikes) | AI-powered recommendations for similar contacts and companies |\n| [**Buying Group**](#tag/Buying-Group) | Identify decision makers, champions, and end users within target accounts |\n| [**Contacts Tables**](#tag/Contacts-Tables) | Persist, organize, and enrich contacts in reusable tables |\n| [**Companies Tables**](#tag/Companies-Tables) | Persist, organize, and enrich companies in reusable tables |\n| [**Signals**](#tag/Signals) | Real-world activity data for contacts and companies |\n| [**Website Visitors**](#tag/Website-Visits) | Companies ranked by website-visit signals for your tracked domains |\n| [**Conversations**](#tag/Conversations) | Search recorded sales conversations and fetch their transcripts |\n| [**Filters**](#tag/Filters) | Discover valid filter values for prospecting |\n| [**Webhooks**](#tag/Webhooks) | Real-time signal notifications via HTTP callbacks |\n| [**Account**](#tag/Account) | Usage, credits, rate limits, and pricing |\n\n
\n\n **Waterfall Reveal for Contact Enrichment.**\n\n Enrich Contacts now supports `waterfallEnabled`. Fall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts. On by default once your account has it turned on - pass `waterfallEnabled: false` to opt a specific call out. [See Enrich Contacts](#operation/enrichContacts).\n\n
\n\n---\n\n## Data Source and Privacy\n\n**Lusha is a search platform.** The data provided is not created or directly managed by Lusha. It is sourced from publicly available information and trusted business partners.\n\nFor more details on how we collect and handle data, see our [Privacy Policy](https://lusha.com/legal/privacy-notice/).\n\n---\n\n## Legal Notices\n\n(a) Data brokers and other third-party platforms may not embed, expose, or otherwise provide access to the Lusha API, or to Data obtained through it, on or through their own website, product, or service, without Lusha's prior written consent.\n\n(b) Data obtained through the API may not be used to train or develop AI/ML systems, subject to the terms and exceptions outlined in the [Terms and Conditions](https://lusha.com/legal/terms).\n\n---\n\n## Authentication\n\nAll API requests require an **API key** linked to your Lusha account and plan. Pass your key in the `api_key` request header on every call.\n\n> Generate and manage your API key in the [Lusha dashboard](https://dashboard.lusha.com/enrich/api).\n\nStore your API key securely and use it only in **server-side environments**.\n\n---\n\n## Rate Limiting\n\nLusha enforces rate limits on a per-plan basis to ensure fair usage and platform stability. Limits are applied across multiple time windows (per minute, per hour, and per day), and vary depending on your account plan.\n\nRate limits for the **Credit Usage API** differ from standard endpoint limits.\n\n> **Note:** To check your current plan's limits, visit the [Lusha Help Center](https://info.lusha.com/en/articles/163856-all-there-is-to-know-about-lusha-s-api) or contact your account manager.\n\n**Rate Limit Response Headers**\n\n| Header | Description |\n|--------|-------------|\n| `x-rate-limit-daily` | Total requests allowed per day |\n| `x-daily-requests-left` | Requests remaining in your daily quota |\n| `x-daily-usage` | Requests made in the current daily period |\n| `x-rate-limit-hourly` | Total requests allowed per hour |\n| `x-hourly-requests-left` | Requests remaining in your hourly quota |\n| `x-hourly-usage` | Requests made in the current hourly period |\n| `x-rate-limit-minute` | Total requests allowed per minute |\n| `x-minute-requests-left` | Requests remaining in the current minute window |\n| `x-minute-usage` | Requests made in the current minute window |\n\n---\n## Error Codes\n\nLusha uses standard HTTP status codes to indicate the result of each request.\n\n| Code | Name | Description |\n|------|------|-------------|\n| `200` | OK | Request was successful |\n| `400` | Bad Request | Request is malformed or missing required fields |\n| `401` | Unauthorized | API key is missing or invalid |\n| `402` | Payment Required | Insufficient credits or payment needed |\n| `403` | Forbidden | Account is inactive. Contact support@lusha.com |\n| `404` | Not Found | Endpoint or resource does not exist |\n| `429` | Too Many Requests | Rate limit or daily quota exceeded |\n| `451` | Unavailable For Legal Reasons | Request blocked due to GDPR regulations |\n| `499` | Client Closed Request | Request timed out before completing |\n| `5XX` | Server Error | Issue on Lusha's end. Retry with exponential backoff |\n\n**Error Response Format**\n\n```json\n{\n \"statusCode\": 400,\n \"message\": \"Invalid request parameters\"\n}\n```\n\n**Tables-specific error codes**\n\n| Code | Status | Meaning |\n|---|---|---|\n| `TABLE_NOT_FOUND` | 404 | The `table_id` does not exist or is not accessible to this account |\n| `COLUMN_NOT_FOUND` | 404 | The `column_id` does not exist on the given table |\n| `TABLE_NAME_CONFLICT` | 409 | A table with this name already exists |\n\nTables error bodies use the shape `{ \"message\": \"...\", \"code\": , ... }` rather than the `statusCode`/`errors` shape used elsewhere in this doc.\n\n**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities per table · max 500 tables per account · `page` 0–100 · `size` default 100.\n\n**Tips for Handling Errors**\n\n- Verify your API key is correct and active\n- Read the `message` field for specific troubleshooting details\n- For `429` errors, wait before retrying\n- For `5XX` errors, use exponential backoff before retrying\n", "contact": { "name": "Lusha Support", "url": "https://api.lusha.com", "email": "support@lusha.com" }, "termsOfService": "https://lusha.com/legal/terms", "x-privacy-policy": { "name": "Privacy Policy", "url": "https://lusha.com/legal/privacy-notice/" } }, "servers": [ { "url": "https://api.lusha.com", "description": "Production server" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Search", "description": "**Search APIs:** Find contacts or companies using known identifiers.\n\nLook up contacts by `id`, `linkedinUrl`, `email`, or `firstName` + `lastName` + `companyName`/`companyDomain`. Look up companies by `id`, `name`, or `domain`.\n\nReturns a non-PII preview of each profile with a `has` field listing available data points and a `canReveal` field showing what can be unlocked via Enrich.\n\n> **Billing:** Charged per successful result via the `api_search` action.\n", "x-tag-expanded": true }, { "name": "Enrich", "description": "**Enrich APIs:** Retrieve full profile data for contacts or companies by ID.\n\nPass IDs from Search results to reveal emails, phones, and full firmographic data.\n\n> **Billing:** Charged per revealed field via per-datapoint pricing (`revealEmail`, `revealPhone`, `reveal_company`).\n", "x-tag-expanded": true }, { "name": "Search & Enrich", "description": "**Search & Enrich APIs:** Find and retrieve full contact or company data in a single call.\n\nCombines Search and Enrich into one request. Provide identifiers and control what gets revealed via the `reveal` field. Premium data points are never returned unless you request them explicitly in `reveal`.\n\n> **Billing:** Two charges apply - one for the search (`api_search`) and one per revealed field.\n", "x-tag-expanded": true }, { "name": "Prospecting", "description": "**Prospecting APIs:** Filter-based search for contacts and companies.\n\nUse prospecting to find new records that match your Ideal Customer Profile (ICP). Apply rich filters across:\n\n- **Contact attributes:** title, seniority, location, signals\n- **Company attributes:** size, revenue, industry, technologies, intent\n\nPass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables) or [Companies Tables](#tag/Companies-Tables).\n\n> **Billing:** Uses the capture/charge model with `api_search` actions. Signal charges apply additionally.\n", "x-tag-expanded": true }, { "name": "Lookalikes", "description": "**Lookalike APIs:** Use AI-powered recommendations to discover contacts and companies similar to your best existing customers. The Contact Lookalikes and Company Lookalikes endpoints return paginated results you can pipe directly into Enrich for full data.\n\nPass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables) or [Companies Tables](#tag/Companies-Tables).\n", "x-tag-expanded": true }, { "name": "Buying Group", "description": "**Buying Group API:** Identify and prioritize the buying committee within a set of target companies.\n\nSupply up to 25 companies by `domain` or Lusha company `id`. The model scores and labels each returned contact with a persona role - `decision_maker`, `potential_champion`, or `end_user` - so you can prioritize outreach across the buying committee instead of working one contact at a time.\n\nResults are lightweight previews grouped by company. Use [Enrich Contacts](#operation/enrichContacts) with the returned `id` to reveal emails and phones.\n\n> **Billing:** Charged per contact returned via the `buyingGroupContact` action.\n", "x-tag-expanded": true }, { "name": "Contacts Tables", "description": "**Contacts Tables API:** Create and manage persistent tables of contacts inside Lusha.\n\nTables are spreadsheets with configurable columns - default Lusha fields, enrichment data, Signals, AI insights, premium data points, CRM fields, and custom fields. Populate a table directly through the endpoints below, or pass `tableId` on Prospecting, Enrich, Signals, or Lookalike calls to persist those results automatically.\n\nEvery surface that touches table data - this API, MCP, and the Workspace UI - reads and writes the same underlying data. Changes made through one surface are reflected on the others.\n\n**Working with tables:**\n- **Tables** - create, list, get status, update (rename/archive/visibility), delete\n- **Entities** - add, remove, or read the rows in a table\n- **Columns** - browse the Lusha column catalog, add columns, list, remove, or run a column across a table's rows\n\n**Owner resolution:** `owner.email` resolves to a user on your account and determines table ownership. **Required on every call when authenticating with an API key** - omitting it returns `400`. Optional for OAuth/token callers, since the caller is already identified by the token. Sent in the body as `owner: { email }` on `POST`/`PATCH` calls (and on `DELETE .../entities`, which carries a body); sent as a `?email=` query parameter on other `GET`/`DELETE` calls, which have no body.\n\n**Billing:**\n- Adding contacts to a table is free.\n- Reading entities (`GET .../entities`) charges per row returned.\n- Create / List / Get / Update / Delete / Column Catalog / Add Columns / List Columns / Remove Column / Remove Entities are free. (Add Columns is free today - credits aren't charged for it yet.)\n- Running a column charges per row per the column's tier (contact enrichment per row with data; signal/AI/score per row per run).\n- Non-public-API-plan accounts always resolve to `0` credits charged.\n\n**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities per table · max 500 tables per account.\n\nSee also: [Companies Tables](#tag/Companies-Tables).\n", "x-tag-expanded": true }, { "name": "Companies Tables", "description": "**Companies Tables API:** Create and manage persistent tables of companies inside Lusha.\n\nTables are spreadsheets with configurable columns - default Lusha fields, enrichment data, Signals, AI insights, premium data points, CRM fields, and custom fields. Populate a table directly through the endpoints below, or pass `tableId` on Prospecting, Enrich, Signals, or Lookalike calls to persist those results automatically.\n\nEvery surface that touches table data - this API, MCP, and the Workspace UI - reads and writes the same underlying data. Changes made through one surface are reflected on the others.\n\n**Working with tables:**\n- **Tables** - create, list, get status, update (rename/archive/visibility), delete\n- **Entities** - add, remove, or read the rows in a table\n- **Columns** - browse the Lusha column catalog, add columns, list, remove, or run a column across a table's rows\n\n**Owner resolution:** `owner.email` resolves to a user on your account and determines table ownership. **Required on every call when authenticating with an API key** - omitting it returns `400`. Optional for OAuth/token callers, since the caller is already identified by the token. Sent in the body as `owner: { email }` on `POST`/`PATCH` calls (and on `DELETE .../entities`, which carries a body); sent as a `?email=` query parameter on other `GET`/`DELETE` calls, which have no body.\n\n**Billing:**\n- Adding companies to a table charges `reveal_company` per **newly added** company, deduped so duplicates and already-present companies aren't charged again.\n- Reading entities (`GET .../entities`) charges per row returned.\n- Create / List / Get / Update / Delete / Column Catalog / Add Columns / List Columns / Remove Column / Remove Entities are free. (Add Columns is free today - credits aren't charged for it yet.)\n- Running a column charges per row per the column's tier (company enrichment once per company per table - re-runs on an already-paid company are free; signal/AI/score per row per run).\n- Non-public-API-plan accounts always resolve to `0` credits charged.\n\n**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities per table · max 500 tables per account.\n\nSee also: [Contacts Tables](#tag/Contacts-Tables).\n", "x-tag-expanded": true }, { "name": "Signals", "description": "Real-world activity data for contacts and companies.\n\nSignals are available as standalone endpoints or as an optional `signals` filter on Search and Prospecting endpoints.\n\n\n**Contact signal types:** `promotion`, `companyChange`, `allSignals`\n\n----\n\n**Company signal types:** `headcountIncrease1m/3m/6m/12m`, `headcountDecrease1m/3m/6m/12m`, `surgeInHiring`, `surgeInHiringByDepartment`, `surgeInHiringByLocation`, `websiteTrafficIncrease`, `websiteTrafficDecrease`, `itSpendIncrease`, `itSpendDecrease`, `riskNews`, `commercialActivityNews`, `corporateStrategyNews`, `financialEventsNews`, `peopleNews`, `marketIntelligenceNews`, `productActivityNews`, `allSignals`\n\n----\n\n**Signal Score:** Use [Score Companies by Signal Activity](#operation/getCompanySignalScores) or [Score Contacts by Signal Activity](#operation/getContactSignalScores) to get a single aggregate momentum score ([0,1]) plus the active signal breakdown for a batch of entities, rather than a raw event list.\n\n----\n\nCredits are charged per matched signal per result via `showSignalsContact` or `showSignalsCompany`.\n\nPass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables) or [Companies Tables](#tag/Companies-Tables).\n", "x-tag-expanded": true }, { "name": "Website Visits", "description": "Retrieve companies ranked by website-visit signals for your tracked domains.\n\n Domains must be configured for tracking in the dashboard. Each result combines a V3 company firmographic preview with behavioral visit metrics (score, sessions, unique visitors, avg session length, and more).\n", "x-tag-expanded": true }, { "name": "Conversations", "description": "**Conversations API:** Search the sales conversations recorded by Lusha Conversations for your account, and fetch speaker-attributed transcripts.\n\nSearch Conversations returns each conversation's metadata, AI summary, action items, risks, objections, competitor mentions, coaching analysis, and chapters - transcripts are not included. Fetch the transcript for a single conversation separately.\n\n**Two search modes on one contract:**\n- **Keyword mode** - supply `query` to rank conversations by transcript content. All other filters are ignored.\n- **Filter mode** - omit `query` and supply the structural filters (dates, contact names, company domains, meeting titles).\n\nOnly conversations belonging to your account whose post-call processing has completed are returned. `summary`, `coaching`, and `chapters` come from an asynchronous pipeline and are `null`/empty until it has run - a `null` summary means \"analysis not ready yet\", not \"nothing found\".\n\n> **Billing:** Search charges 1 credit per block of up to 25 conversations returned (via `ci_meeting_data_export`); a request that returns nothing is free. Transcript charges 1 credit per successful request (via `ci_transcript_analysis`); a `404` is never charged. While the relevant action isn't yet seeded on your account's pricebook, the endpoint stays free (`billing.creditsCharged` is `0`).\n", "x-tag-expanded": true }, { "name": "Filters", "description": "**Filter APIs:** Retrieve available filter values for prospecting.\n\nUse the discovery endpoints to list all available filter types, then fetch valid values for a specific filter type before building a prospecting request.\n\n**Contact filter types:** `departments`, `seniority`, `existingDataPoints`, `countries`, `locations`\n\n**Company filter types:** `names`, `sizes`, `revenues`, `locations`, `sics`, `naics`, `industriesLabels`, `intentTopics`, `technologies`\n", "x-tag-expanded": true }, { "name": "Webhooks", "description": "Subscribe to real-time notifications when contacts change jobs or companies experience key business events.\n\nWebhooks deliver HTTP POST requests to your endpoints when signals occur - from promotions and job changes to company growth.\n\n> For a full list of available signals, refer to [**Signal Options**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions).\n---\n**Key Features:**\n- Real-time contact & company signal notifications\n- Bulk subscription management (up to 25 items per request)\n- Secure delivery with HMAC-SHA256 signatures\n- Delivery monitoring with audit logs\n\n **Available Endpoints:**\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| POST | `/api/subscriptions` | Create subscriptions (bulk supported) |\n| GET | `/api/subscriptions` | List all subscriptions |\n| GET | `/api/subscriptions/{id}` | Get subscription by ID |\n| PATCH | `/api/subscriptions/{id}` | Update subscription |\n| POST | `/api/subscriptions/delete` | Delete subscriptions (bulk supported) |\n| POST | `/api/subscriptions/{id}/test` | Test subscription delivery |\n| GET | `/api/audit-logs` | Get webhook delivery logs |\n| GET | `/api/audit-logs/stats` | Get delivery statistics |\n| GET | `/api/account/secret` | Get account webhook secret |\n| POST | `/api/account/secret/regenerate` | Regenerate account secret |\n| POST | `/api/subscriptions/opt-out` | Subscribe to contact opt-out notifications |\n\n> **Webhook Delivery Acknowledgment:** When receiving webhook deliveries (POST requests), your endpoint must acknowledge with a specific response format. See the [Create Subscription](#operation/createSubscription) endpoint for the required acknowledgment structure.\n ---\n\n
\nRate Limits\n\n| Operation | Limit |\n|-----------|-------|\n| API Requests | 100 requests/minute per account |\n| Create Subscriptions | 25 items per request |\n| Delete Subscriptions | 25 items per request |\n\n
\n\n---\n\n
\nSecurity & Verification\n\n**HTTPS Requirement:**\n- Production webhook URLs **must** use HTTPS\n- HTTP URLs are not accepted\n\n**Signature Verification:**\n\nAll webhook deliveries include an `X-Lusha-Signature` header containing an HMAC-SHA256 signature. Verify this signature to ensure the request is from Lusha:\n\n1. Extract the `X-Lusha-Signature` and `X-Lusha-Timestamp` headers\n2. Concatenate: `timestamp + \".\" + JSON.stringify(payload)`\n3. Compute HMAC-SHA256 using your webhook secret\n4. Compare the computed signature with the received signature\n\n**Example (Node.js):**\n```javascript\nconst crypto = require('crypto');\n\nfunction verifySignature(payload, signature, timestamp, secret) {\n const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;\n const expectedSignature = crypto\n .createHmac('sha256', secret)\n .update(signedPayload)\n .digest('hex');\n \n return crypto.timingSafeEqual(\n Buffer.from(signature),\n Buffer.from(expectedSignature)\n );\n}\n```\n\n> **Security Best Practice:** Always verify webhook signatures to prevent spoofed requests.\n\n
\n\n---\n\n
\nCredits & Billing\n\n**Credit Charges:**\n- Credits are charged when signals are detected and delivered to your webhook\n- The `creditsCharged` field in the webhook payload indicates how many credits were used\n- Credits are deducted from your account balance per signal type\n\n**No Duplicate Charges:**\n- Each signal is delivered once and charged once\n- Webhook delivery retries do not incur additional charges\n\n
\n\n---\n\n
\nError Response Format\n\nAll error responses follow this format:\n```json\n{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"errors\": [\"entityType must be one of: contact, company\"]\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `statusCode` | number | HTTP status code |\n| `message` | string | Error message |\n| `errors` | string[] | Detailed error messages (optional) |\n\n
\n \n---\n", "x-tag-expanded": true }, { "name": "Account", "description": "**Account API:** Retrieve account usage, credit balance, rate limits, plan details, and pricing.\n\nUse this endpoint to monitor consumption and understand the credit cost of each action type in the public API flow.\n\n> **Rate limit:** 5 requests per minute.\n", "x-tag-expanded": true } ], "paths": { "/v3/contacts/search": { "post": { "tags": [ "Search" ], "summary": "Search Contacts", "operationId": "searchContacts", "description": "Look up contacts by identifier. Returns a non-PII preview of each profile - no emails or phone numbers.\n\n**Accepted identifiers (one required per contact):**\n- Lusha contact `id`\n- `linkedinUrl`\n- `email`\n- `firstName` + `lastName` + `companyName` or `companyDomain`\n\nUp to 100 contacts per request. Each result includes:\n- `has` - data points available on this profile\n- `canReveal` - what you can unlock via Enrich Contacts, and the credit cost\n\nPass a `signals` filter to narrow results to contacts with recent activity (e.g. promotion, job change).\n\n> **Billing:** Charged per successful result via the `api_search` action.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactsSearchRequest" }, "example": { "contacts": [ { "clientReferenceId": "my-ref-1", "firstName": "Orit", "lastName": "Shilvock", "companyName": "Lusha", "companyDomain": "lusha.com" }, { "clientReferenceId": "my-ref-2", "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger" }, { "clientReferenceId": "my-ref-3", "email": "gal.ashkelon@lusha.com" }, { "clientReferenceId": "my-ref-4", "id": "12345" } ], "options": { "includePartialProfiles": true } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactsSearchResponse" }, "example": { "requestId": "6e4b1192-9440-42c4-9a3e-793ddef6d73c", "results": [ { "clientReferenceId": "my-ref-1", "id": "4415824633", "firstName": "Orit", "lastName": "Shilvock", "jobTitle": { "title": "Vice President of Partnerships", "departments": [ "Business Development" ], "seniority": "Vice President" }, "company": { "id": "16303253", "name": "Lusha", "domain": "www.lusha.com", "industry": "Technology, Information & Media" }, "location": { "country": "Israel", "city": "Tel Aviv" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/orit-shilvock-6243bb5" }, "has": [ "firstName", "lastName", "jobTitle", "location", "socialLinks", "emails" ], "canReveal": [ { "field": "emails", "credits": 1 } ] }, { "clientReferenceId": "my-ref-2", "id": "4415824679", "firstName": "Shmulik", "lastName": "Willinger", "jobTitle": { "title": "Chief Architect", "departments": [ "Engineering & Technical" ], "seniority": "C-Suite" }, "company": { "id": "16303253", "name": "Lusha", "domain": "www.lusha.com", "industry": "Technology, Information & Media" }, "location": { "country": "Israel", "city": "Tel Aviv" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/shmulikwillinger" }, "has": [ "firstName", "lastName", "jobTitle", "location", "socialLinks", "emails" ], "canReveal": [ { "field": "emails", "credits": 1 } ] }, { "clientReferenceId": "my-ref-3", "id": "4415824664", "firstName": "Gal", "lastName": "Ashkelon", "jobTitle": { "title": "Global Partner Program Manager", "departments": [ "Business Development" ], "seniority": "Manager" }, "company": { "id": "16303253", "name": "Lusha", "domain": "www.lusha.com", "industry": "Technology, Information & Media" }, "location": { "country": "Israel", "city": "Tel Aviv" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/gal-ashkelon-39408557" }, "has": [ "firstName", "lastName", "jobTitle", "location", "socialLinks", "emails" ], "canReveal": [ { "field": "emails", "credits": 1 } ] }, { "clientReferenceId": "my-ref-4", "error": { "code": "NOT_FOUND", "message": "Contact not found" } } ], "billing": { "creditsCharged": 1, "resultsReturned": 3 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/enrich": { "post": { "tags": [ "Enrich" ], "summary": "Enrich Contacts", "operationId": "enrichContacts", "description": "Reveal full contact data for contacts you've already found via Search Contacts.\n\nPass up to 100 contact `ids` (from the search response). Use the `reveal` field to control what gets unlocked:\n- `emails` - work and personal email addresses\n- `phones` - mobile and direct phone numbers\n- Omit `reveal` to get both by default\n\n---\n\n### Waterfall Reveal\nFall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts.\n\nIf **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.\n\n\nPass `waterfallEnabled: false` to opt a specific call out:\n\n ```json\n \"reveal\": [\"emails\", \"phones\"],\n \"waterfallEnabled\": false\n ```\n\n- `reveal` controls **which fields** come back.\n- `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.\n- Provider order isn't configurable - Lusha manages that internally.\n- If Data Waterfall is off or no providers are enabled on your account, `waterfallEnabled` has no effect either way.\n---\n> **Tip:** If `canReveal.credits` is `0` in the search response, that data has already been revealed for your account - re-enriching it is free.\n\n> **Billing:** Charged per revealed field (email or phone) via per-datapoint pricing.\n\n> **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).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactsEnrichRequest" }, "examples": { "standard": { "summary": "Standard reveal (waterfall runs automatically if enabled on your account)", "value": { "ids": [ "4389064654", "4389064624" ], "reveal": [ "emails", "phones" ] } }, "waterfallDisabled": { "summary": "Opt this call out of the waterfall", "value": { "ids": [ "4389064654", "4389064624" ], "reveal": [ "emails", "phones" ], "waterfallEnabled": false } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactsEnrichResponse" }, "example": { "requestId": "71581363-f73d-46e1-9115-ecbd771b964b", "results": [ { "id": "4389064654", "firstName": "Daniel", "lastName": "Turgeman", "fullName": "Daniel Turgeman", "jobTitle": { "title": "Technical Product Manager", "departments": [ "Product" ], "seniority": "Manager" }, "location": { "country": "Israel", "countryIso2": "IL", "city": "Tel Aviv", "continent": "Asia", "coordinates": [ 34.78057098388672, 32.08087921142578 ], "isEuContact": false }, "tags": [], "emails": [ { "email": "daniel.t@lusha.com", "type": "work", "confidence": "A+", "updateDate": "2026-04-23" } ], "phones": [], "company": { "id": "16303253", "name": "Lusha", "domain": "www.lusha.com", "industry": "Technology, Information & Media" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/daniel-turgeman-49676b161" }, "previousEmployment": [], "updateDate": "2026-04-23" } ], "billing": { "creditsCharged": 2, "resultsReturned": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/search-and-enrich": { "post": { "tags": [ "Search & Enrich" ], "summary": "Search and Enrich Contacts", "operationId": "searchAndEnrichContacts", "description": "Find contacts and reveal their full data in a single call. Combines Search and Enrich into one request.\n\nProvide contact identifiers the same way you would for Search Contacts. Use the `reveal` field to control what gets unlocked (`emails`, `phones`, or both).\n\nUp to 100 contacts per request.\n\n> **Billing:** Two charges apply - one for the search (`api_search`) and one per revealed field. The `billing.creditsCharged` in the response reflects the total.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactsSearchAndEnrichRequest" }, "example": { "contacts": [ { "clientReferenceId": "my-ref-1", "firstName": "Orit", "lastName": "Shilvock", "companyName": "Lusha", "companyDomain": "lusha.com" }, { "clientReferenceId": "my-ref-2", "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger" } ], "reveal": [ "emails", "phones" ], "options": { "includePartialProfiles": true } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactsSearchAndEnrichResponse" }, "example": { "requestId": "211ee5da-3c0d-4621-9fa5-140e393a3ced", "results": [ { "clientReferenceId": "my-ref-1", "id": "4389064704", "firstName": "Orit", "lastName": "Shilvock", "fullName": "Orit Shilvock", "emails": [ { "email": "orit.shilvock@lusha.com", "type": "work", "confidence": "A+", "updateDate": "2026-04-23" } ], "phones": [], "tags": [], "previousEmployment": [], "updateDate": "2026-04-23" } ], "billing": { "creditsCharged": 2, "resultsReturned": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/companies/search": { "post": { "tags": [ "Search" ], "summary": "Search Companies", "operationId": "searchCompanies", "description": "Look up companies by identifier. Returns a preview of each company profile.\n\n**Accepted identifiers (at least one required per company):**\n- Lusha company `id`\n- `name`\n- `domain`\n\nUp to 100 companies per request. Each result includes a `has` field listing the data available via Enrich Companies.\n\nPass a `signals` filter to narrow results to companies showing specific activity (e.g. headcount growth, hiring surge).\n\n> **Billing:** Charged per successful result via the `api_search` action.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompaniesSearchRequest" }, "example": { "companies": [ { "clientReferenceId": "comp-ref-1", "name": "Lusha" }, { "clientReferenceId": "comp-ref-2", "domain": "salesforce.com" }, { "clientReferenceId": "comp-ref-3", "id": "16303253" } ], "options": { "includePartialProfiles": true } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompaniesSearchResponse" }, "example": { "requestId": "abd4a213-d33b-4565-b9b6-55c19c65cc47", "results": [ { "clientReferenceId": "comp-ref-1", "id": "16303253", "name": "Lusha", "domain": "www.lusha.com", "employeeCount": { "exact": 364, "min": 201, "max": 500 }, "industry": "Technology, Information & Media", "location": { "city": "Boston", "state": "Massachusetts", "country": "United States", "countryIso2": "US", "continent": "North America" }, "socialLinks": { "linkedin": "https://www.linkedin.com/company/lushadata" }, "has": [ "alternativeName", "alternativeDomains", "description", "companyType", "yearFounded", "subIndustry", "specialities", "sicCodes", "naicsCodes", "additionalLocations", "linkedinFollowers", "funding", "popularityTier", "logoUrl", "employeesByDepartment", "employeesByLocation", "employeesBySeniority", "competitors", "businessModel", "emails", "keywords", "socialLinks" ], "canReveal": [ { "field": "employeesByDepartment", "credits": 1 }, { "field": "employeesByLocation", "credits": 1 }, { "field": "employeesBySeniority", "credits": 1 }, { "field": "competitors", "credits": 1 } ] }, { "clientReferenceId": "comp-ref-2", "id": "12790225", "name": "Salesforce", "domain": "www.salesforce.com", "employeeCount": { "exact": 88711, "min": 100001, "max": 10000000 }, "industry": "Technology, Information & Media", "location": { "city": "San Francisco", "state": "California", "country": "United States", "countryIso2": "US", "continent": "North America" }, "socialLinks": { "linkedin": "https://www.linkedin.com/company/salesforce" }, "has": [ "alternativeName", "alternativeDomains", "description", "companyType", "subIndustry", "sicCodes", "naicsCodes", "additionalLocations", "linkedinFollowers", "revenueRange", "intent", "popularityTier", "logoUrl", "employeesByDepartment", "employeesByLocation", "employeesBySeniority", "competitors", "phones", "emails", "socialLinks" ], "canReveal": [ { "field": "employeesByDepartment", "credits": 1 }, { "field": "employeesByLocation", "credits": 1 }, { "field": "employeesBySeniority", "credits": 1 }, { "field": "competitors", "credits": 1 }, { "field": "intent", "credits": 0 } ] } ], "billing": { "creditsCharged": 1, "resultsReturned": 3 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/companies/enrich": { "post": { "tags": [ "Enrich" ], "summary": "Enrich Companies", "operationId": "enrichCompanies", "description": "Reveal full company data for companies you've already found via Search Companies.\n\nPass up to 100 company `ids` (from the search response). Each enriched result includes:\n- Firmographics: size, revenue range, year founded, company type\n- Industry: primary industry, sub-industry, SIC/NAICS codes\n- Locations: HQ and additional office sites\n- Technologies, funding rounds, buyer intent topics\n- LinkedIn followers, logo URL, social links (LinkedIn, Facebook, X, Instagram, YouTube, TikTok)\n- Open job posting counts: total and breakdowns by department, location, and seniority\n- Ownership: immediate parent (`directParent`) and top of the ownership tree (`ultimateParent`)\n\n> **Billing:** Charged per successful result via the `reveal_company` action.\n\n> **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).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompaniesEnrichRequest" }, "example": { "ids": [ "16303253", "12790225", "18654301" ], "reveal": [ "employeesByLocation", "employeesByDepartment", "employeesBySeniority", "competitors", "intent", "openJobsTotal", "openJobsByDepartment", "directParent", "ultimateParent" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompaniesEnrichResponse" }, "example": { "requestId": "5e8f5993-a0a3-4510-bc90-7b4506272c68", "results": [ { "id": "16303253", "name": "Lusha", "alternativeName": "lusha", "domain": "www.lusha.com", "alternativeDomains": [ "lusha.com" ], "description": "Lusha is the leader in Sales Streaming – a new sales paradigm that streams top leads straight to salespeople and handles all the outreach, so they can escape the lead grind and just sell.", "companyType": "Private Company", "yearFounded": 2016, "employeeCount": { "exact": 364, "min": 201, "max": 500 }, "industry": "Technology, Information & Media", "subIndustry": "Software Development", "specialities": [ "data accuracy", "data enrichment", "lead discovery", "lead generation", "prospecting", "sales enablement", "sales intelligence", "software development" ], "sicCodes": [ { "code": 7371, "description": "Custom computer programming services" } ], "naicsCodes": [ { "code": 541511, "description": "Custom Computer Programming Services" } ], "location": { "city": "Boston", "state": "Massachusetts", "country": "United States", "countryIso2": "US", "continent": "North America", "zipCode": "02199" }, "additionalLocations": [ { "city": "New York City", "state": "New York", "country": "United States", "countryIso2": "US", "continent": "North America" } ], "socialLinks": { "linkedin": "https://www.linkedin.com/company/lushadata", "facebook": "https://www.facebook.com/lusha", "x": "https://x.com/lusha", "instagram": [ "https://www.instagram.com/lusha" ], "youtube": [ "https://www.youtube.com/c/lushadata" ], "tiktok": [ "https://www.tiktok.com/@lusha" ] }, "linkedinFollowers": 64339, "funding": { "rounds": [ { "currency": "USD", "roundAmount": 205000000, "roundType": "Private Equity Round", "roundDate": "Nov 10, 2021" }, { "currency": "USD", "roundAmount": 40000000, "roundType": "Private Equity Round", "roundDate": "Feb 10, 2021" } ], "totalRounds": 2, "totalRoundsAmount": 245000000, "currency": "USD", "isIpo": false, "lastRoundType": "Private Equity Round", "lastRoundAmount": 205000000, "lastRoundDate": "Nov 10, 2021" }, "technologies": [ "amazon", "google analytics" ], "popularityTier": 1, "logoUrl": "https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg", "employeesByDepartment": [ { "department": "Business Development", "count": 14 }, { "department": "Consulting", "count": 10 }, { "department": "Customer Service", "count": 28 }, { "department": "Engineering & Technical", "count": 95 }, { "department": "Finance", "count": 14 }, { "department": "General Management", "count": 41 }, { "department": "Human Resources", "count": 16 }, { "department": "Information Technology", "count": 13 }, { "department": "Legal", "count": 7 }, { "department": "Marketing", "count": 31 }, { "department": "Operations", "count": 22 }, { "department": "Other", "count": 35 }, { "department": "Product", "count": 38 }, { "department": "Research & Analytics", "count": 42 }, { "department": "Sales", "count": 72 } ], "employeesByLocation": [ { "country": "Israel", "state": null, "count": 301 }, { "country": "United States", "state": null, "count": 45 }, { "country": "United States", "state": "Massachusetts", "count": 30 }, { "country": "Brazil", "state": null, "count": 22 }, { "country": "France", "state": null, "count": 10 } ], "employeesBySeniority": [ { "seniority": "C-Suite", "count": 12 }, { "seniority": "Director", "count": 35 }, { "seniority": "Founder", "count": 33 }, { "seniority": "Intern", "count": 1 }, { "seniority": "Manager", "count": 141 }, { "seniority": "Non-Manager", "count": 163 }, { "seniority": "Partner", "count": 6 }, { "seniority": "Senior", "count": 59 }, { "seniority": "Vice President", "count": 9 } ], "competitors": [ { "id": "2497917", "name": "Clearbit", "domain": "clearbit.com" }, { "id": "9781263", "name": "Hunter.io", "domain": "hunter.io" }, { "id": "40857684", "name": "MCJ Solutions Inc", "domain": "zoominfo.com" }, { "id": "157961346", "name": "PMc", "domain": "apollo.io" } ], "businessModel": [ "B2B" ], "emails": [ { "email": "Support@Lusha.com" } ], "keywords": [ "contact information", "data accuracy", "data enrichment", "lead discovery", "lead generation", "prospecting", "sales cadence", "sales enablement", "sales intelligence", "sales playlist", "sales streaming", "software development" ], "openJobs": { "total": 47, "byDepartment": [ { "department": "Engineering & Technical", "count": 21 }, { "department": "Sales", "count": 9 } ] }, "directParent": null, "ultimateParent": null }, { "id": "12790225", "name": "Salesforce", "alternativeName": "salesforce", "domain": "www.salesforce.com", "alternativeDomains": [ "salesforce.com" ], "description": "We're the #1 AI CRM-where humans with agents drive customer success together with AI, data, and Customer 360 apps on one platform.", "companyType": "Public Company", "employeeCount": { "exact": 88711, "min": 100001, "max": 10000000 }, "industry": "Technology, Information & Media", "subIndustry": "Software Development", "sicCodes": [ { "code": 7371, "description": "Custom computer programming services" } ], "naicsCodes": [ { "code": 541511, "description": "Custom Computer Programming Services" } ], "location": { "city": "San Francisco", "state": "California", "country": "United States", "countryIso2": "US", "continent": "North America", "zipCode": "94105" }, "additionalLocations": [ { "country": "United States", "countryIso2": "US", "continent": "North America" }, { "city": "Chicago", "state": "Illinois", "country": "United States", "countryIso2": "US", "continent": "North America" }, { "city": "London", "country": "United Kingdom", "countryIso2": "GB", "continent": "Europe" }, { "city": "Tel Aviv", "country": "Israel", "countryIso2": "IL", "continent": "Asia" } ], "socialLinks": { "linkedin": "https://www.linkedin.com/company/salesforce" }, "linkedinFollowers": 6417067, "revenueRange": { "min": 10000000000, "max": 100000000000 }, "intent": { "detectedTopics": [ { "topicName": "Cognism Limited", "metadata": { "topicScore": 85, "topicTrend": "+24" } } ], "topicCount": 1 }, "technologies": [ "amazon", "paypal", "google analytics" ], "popularityTier": 1, "logoUrl": "https://logo.lusha.co/brightdata/year=2024/month=05/day=20/j_lwej8xik12ncr6ge4u.9e1ec373903019beff129694cb926761f065e9af.file_lwejc8mispkz3m1ng.logo_cached.jpg", "employeesByDepartment": [ { "department": "Business Development", "count": 2820 }, { "department": "Consulting", "count": 4963 }, { "department": "Engineering & Technical", "count": 29167 }, { "department": "Finance", "count": 2126 }, { "department": "Marketing", "count": 4793 }, { "department": "Operations", "count": 6117 }, { "department": "Sales", "count": 22316 } ], "employeesByLocation": [ { "country": "United States", "state": null, "count": 46090 }, { "country": "United States", "state": "California", "count": 9928 }, { "country": "India", "state": null, "count": 18527 }, { "country": "United Kingdom", "state": null, "count": 3682 }, { "country": "Ireland", "state": null, "count": 3226 } ], "employeesBySeniority": [ { "seniority": "C-Suite", "count": 1039 }, { "seniority": "Director", "count": 11538 }, { "seniority": "Manager", "count": 18836 }, { "seniority": "Non-Manager", "count": 49493 }, { "seniority": "Senior", "count": 20509 }, { "seniority": "Vice President", "count": 3104 } ], "competitors": [ { "id": "4269625", "name": "iGroup Vietnam - Solutions for Enterprise", "domain": "monday.com" }, { "id": "7237482", "name": "Pipedrive", "domain": "pipedrive.com" }, { "id": "9740086", "name": "Microsoft", "domain": "microsoft.com" }, { "id": "156097472", "name": "Hub Spot", "domain": "hubspot.com" } ], "phones": [ { "number": "+1 800-420-7332" } ], "emails": [ { "email": "datasubjectrequest@salesforce.com" } ], "directParent": null, "ultimateParent": null }, { "id": "18654301", "name": "4D", "domain": "4d.com", "companyType": "Subsidiary", "directParent": { "lushaCompanyId": "v1.XyZw...", "name": "Volaris Group", "domain": "volarisgroup.com" }, "ultimateParent": { "lushaCompanyId": "v1.QrSt...", "name": "Constellation Software Inc.", "domain": "csisoftware.com", "hqCountry": "Canada" } } ], "billing": { "creditsCharged": 14, "resultsReturned": 3 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/companies/search-and-enrich": { "post": { "tags": [ "Search & Enrich" ], "summary": "Search and Enrich Companies", "operationId": "searchAndEnrichCompanies", "description": "Find companies and reveal their full data in a single call. Combines Search and Enrich into one request.\n\nProvide company identifiers the same way you would for Search Companies. Up to 100 companies per request.\n\nUse 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.\n\n> **Billing:** Same as Enrich Companies - charged per successful result via the `reveal_company` action, plus one charge per revealed field.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompaniesSearchAndEnrichRequest" }, "example": { "companies": [ { "clientReferenceId": "comp-ref-1", "name": "Lusha" }, { "clientReferenceId": "comp-ref-2", "domain": "salesforce.com" }, { "clientReferenceId": "comp-ref-3", "domain": "4d.com" } ], "reveal": [ "directParent", "ultimateParent" ], "options": { "includePartialProfiles": true } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompaniesSearchAndEnrichResponse" }, "example": { "requestId": "21fe0733-65d6-436a-8d0c-2c9ac6f263f8", "results": [ { "clientReferenceId": "comp-ref-1", "id": "16303253", "name": "Lusha", "alternativeName": "lusha", "domain": "www.lusha.com", "alternativeDomains": [ "lusha.com" ], "description": "Lusha is the leader in Sales Streaming – a new sales paradigm that streams top leads straight to salespeople and handles all the outreach, so they can escape the lead grind and just sell.", "companyType": "Private Company", "yearFounded": 2016, "employeeCount": { "exact": 364, "min": 201, "max": 500 }, "industry": "Technology, Information & Media", "subIndustry": "Software Development", "specialities": [ "data accuracy", "data enrichment", "lead discovery", "lead generation", "prospecting", "sales enablement", "sales intelligence", "software development" ], "sicCodes": [ { "code": 7371, "description": "Custom computer programming services" } ], "naicsCodes": [ { "code": 541511, "description": "Custom Computer Programming Services" } ], "location": { "city": "Boston", "state": "Massachusetts", "country": "United States", "countryIso2": "US", "continent": "North America", "zipCode": "02199" }, "additionalLocations": [ { "city": "New York City", "state": "New York", "country": "United States", "countryIso2": "US", "continent": "North America" } ], "socialLinks": { "linkedin": "https://www.linkedin.com/company/lushadata" }, "linkedinFollowers": 64339, "funding": { "rounds": [ { "currency": "USD", "roundAmount": 205000000, "roundType": "Private Equity Round", "roundDate": "Nov 10, 2021" }, { "currency": "USD", "roundAmount": 40000000, "roundType": "Private Equity Round", "roundDate": "Feb 10, 2021" } ], "totalRounds": 2, "totalRoundsAmount": 245000000, "currency": "USD", "isIpo": false, "lastRoundType": "Private Equity Round", "lastRoundAmount": 205000000, "lastRoundDate": "Nov 10, 2021" }, "technologies": [ "amazon", "google analytics" ], "popularityTier": 1, "logoUrl": "https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg", "businessModel": [ "B2B" ], "emails": [ { "email": "Support@Lusha.com" } ], "keywords": [ "contact information", "data accuracy", "data enrichment", "lead discovery", "lead generation", "prospecting", "sales enablement", "sales intelligence", "software development" ] }, { "clientReferenceId": "comp-ref-2", "id": "12790225", "name": "Salesforce", "alternativeName": "salesforce", "domain": "www.salesforce.com", "alternativeDomains": [ "salesforce.com" ], "description": "We're the #1 AI CRM-where humans with agents drive customer success together with AI, data, and Customer 360 apps on one platform.", "companyType": "Public Company", "employeeCount": { "exact": 88711, "min": 100001, "max": 10000000 }, "industry": "Technology, Information & Media", "subIndustry": "Software Development", "sicCodes": [ { "code": 7371, "description": "Custom computer programming services" } ], "naicsCodes": [ { "code": 541511, "description": "Custom Computer Programming Services" } ], "location": { "city": "San Francisco", "state": "California", "country": "United States", "countryIso2": "US", "continent": "North America", "zipCode": "94105" }, "additionalLocations": [ { "country": "United States", "countryIso2": "US", "continent": "North America" }, { "city": "Chicago", "state": "Illinois", "country": "United States", "countryIso2": "US", "continent": "North America" }, { "city": "London", "country": "United Kingdom", "countryIso2": "GB", "continent": "Europe" }, { "city": "Tel Aviv", "country": "Israel", "countryIso2": "IL", "continent": "Asia" } ], "socialLinks": { "linkedin": "https://www.linkedin.com/company/salesforce" }, "linkedinFollowers": 6417067, "revenueRange": { "min": 10000000000, "max": 100000000000 }, "intent": { "detectedTopics": [ { "topicName": "Cognism Limited", "metadata": { "topicScore": 85, "topicTrend": "+24" } } ], "topicCount": 1 }, "technologies": [ "amazon", "paypal", "google analytics" ], "popularityTier": 1, "logoUrl": "https://logo.lusha.co/brightdata/year=2024/month=05/day=20/j_lwej8xik12ncr6ge4u.9e1ec373903019beff129694cb926761f065e9af.file_lwejc8mispkz3m1ng.logo_cached.jpg", "phones": [ { "number": "+1 800-420-7332" } ], "emails": [ { "email": "datasubjectrequest@salesforce.com" } ], "directParent": null, "ultimateParent": null }, { "clientReferenceId": "comp-ref-3", "id": "18654301", "name": "4D", "domain": "4d.com", "companyType": "Subsidiary", "directParent": { "lushaCompanyId": "v1.XyZw...", "name": "Volaris Group", "domain": "volarisgroup.com" }, "ultimateParent": { "lushaCompanyId": "v1.QrSt...", "name": "Constellation Software Inc.", "domain": "csisoftware.com", "hqCountry": "Canada" } } ], "billing": { "creditsCharged": 5, "resultsReturned": 3 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/prospecting": { "post": { "tags": [ "Prospecting" ], "summary": "Prospecting Contacts", "operationId": "prospectingContacts", "description": "Search for contacts that match your Ideal Customer Profile using rich filter criteria.\n\n**Filter by contact attributes:**\n- Job title, seniority, department\n- Location (city, state, country, continent)\n- Existing data points (e.g. only contacts with a known work email)\n- Signal activity (promotion, job change)\n\n**Filter by company attributes:**\n- Size, revenue, industry, technologies\n- Location, intent topics, funding\n\nUse `options.maxContactsPerCompany` (1–20) to cap how many contacts are returned per company; `pagination.size` still controls the page size. \n\nUse the returned contact `id` values with Enrich Contacts to reveal emails and phones.\n\n> **Billing:** Charged per result via `api_search`. If signals are requested, an additional charge applies per matched signal per result.\n\n> **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).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ProspectingContactsRequest" }, "example": { "pagination": { "page": 0, "size": 100 }, "filters": { "contacts": { "include": { "departments": [ "Sales" ], "locations": [ { "country": "United States" } ], "existingDataPoints": [ "work_email" ] } }, "companies": { "include": { "locations": [ { "country": "United States" } ], "foundedYear": [ { "min": 2000 } ], "businessModel": [ "B2B" ], "companyType": [ "Public Company" ], "linkedinUrls": [ "https://www.linkedin.com/company/google" ], "keywords": [ "fintech" ] }, "exclude": { "domains": [ "competitor.com" ], "companyType": [ "Self Employed" ] } } }, "tableId": "482910", "options": { "includePartialProfiles": true, "excludeDnc": false, "maxContactsPerCompany": 2 } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ProspectingContactsResponse" }, "example": { "requestId": "fa828378-7a8e-4e5d-9f72-0270e7f7ab51", "pagination": { "page": 0, "size": 50, "total": 670550, "totalGuaranteed": true, "totalDescription": "Exact contact count (up to 2 per company)" }, "results": [ { "id": "670138733", "firstName": "Ting", "lastName": "Tsou" } ], "tableWrite": { "tableId": "482910", "added": 48, "alreadyPresent": 2, "columnsCreated": [], "rowsProcessed": 50, "rowsCharged": 48, "rowsAlreadyPaidInTable": 2 }, "billing": { "creditsCharged": 2, "resultsReturned": 50 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/companies/prospecting": { "post": { "tags": [ "Prospecting" ], "summary": "Prospecting Companies", "operationId": "prospectingCompanies", "description": "Search for companies that match your target market using rich filter criteria.\n\n**Filter by:**\n- Size, revenue range, industry, sub-industry\n- Technologies in use\n- Locations (HQ country, state, city)\n- SIC and NAICS codes\n- Buyer intent topics\n- Signal activity (headcount changes, hiring surges, news events, LinkedIn activity intent)\n\nUse the returned company `id` values with Enrich Companies to get full firmographic data.\n\n> **Billing:** Charged per result via `api_search`. If signals are requested, an additional charge applies per matched signal per result.\n\n> **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).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ProspectingCompaniesRequest" }, "example": { "pagination": { "page": 0, "size": 25 }, "filters": { "companies": { "include": { "sizes": [ { "min": 1, "max": 1000 } ], "revenues": [ { "min": 10000000 } ], "locations": [ { "country": "United States" } ], "technologies": [ "React", "Node.js" ], "technologiesCondition": "or", "mainIndustriesIds": [ 1, 5 ], "intentTopics": [ "Cloud Migration" ], "foundedYear": [ { "min": 1990, "max": 2020 } ], "businessModel": [ "B2B", "B2G" ], "companyType": [ "Public Company", "Private Company" ], "linkedinUrls": [ "https://www.linkedin.com/company/microsoft" ], "keywords": [ "cloud", "artificial intelligence" ], "signals": { "types": [ "headcountIncrease3m", "surgeInHiring" ], "startDate": "2025-01-01" } }, "exclude": { "domains": [ "competitor.com" ], "businessModel": [ "B2C" ], "companyType": [ "Non Profit" ], "keywords": [ "staffing" ] } } }, "tableId": "583021", "options": { "includePartialProfiles": false } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ProspectingCompaniesResponse" }, "example": { "requestId": "f6a7b8c9-d0e1-2345-fabc-678901234567", "results": [ { "id": "16303253", "name": "Lusha", "domain": "lusha.com" } ], "pagination": { "page": 0, "size": 25, "total": 87 }, "tableWrite": { "tableId": "583021", "added": 1, "alreadyPresent": 0, "columnsCreated": [], "rowsProcessed": 1, "rowsCharged": 1, "rowsAlreadyPaidInTable": 0 }, "billing": { "creditsCharged": 1, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/lookalike": { "post": { "tags": [ "Lookalikes" ], "summary": "Contact Lookalikes", "operationId": "getContactLookalikes", "description": "Find contacts similar to a set of seed contacts using AI-powered recommendations.\n\nProvide seed contacts via LinkedIn URLs, emails, Lusha IDs, or name + company. The API returns contacts who share similar roles, seniority, and company profiles.\n\n> **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.\n\n**Pagination without duplicates:**\nOn 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.\n\nUse the `exclude` field to always filter out specific contacts (e.g. existing customers).\n\nResults are lightweight previews. Use Enrich Contacts with the returned `id` to get emails and phones.\n\n> **Billing:** Charged per result via the `lookalikeContact` action.\n\n> **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLookalikesRequest" }, "examples": { "firstRequest": { "summary": "First request - 6 seeds across three identifier types (server generates dedupeSessionId)", "value": { "seeds": { "linkedinUrls": [ "https://www.linkedin.com/in/orit-shilvock-6243bb5", "https://www.linkedin.com/in/shmulikwillinger" ], "emails": [ "gal.ashkelon@lusha.com", "miri.tamir@lusha.com" ], "ids": [ "1234", "4567" ] }, "exclude": { "emails": [ "existing@customer.com" ] }, "limit": 25 } }, "secondRequest": { "summary": "Second request - same 6 seeds, paginating with dedupeSessionId", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "seeds": { "linkedinUrls": [ "https://www.linkedin.com/in/orit-shilvock-6243bb5", "https://www.linkedin.com/in/shmulikwillinger" ], "emails": [ "gal.ashkelon@lusha.com", "miri.tamir@lusha.com" ], "ids": [ "1234", "4567" ] }, "limit": 25 } } } } } }, "responses": { "200": { "description": "Successfully retrieved contact lookalikes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLookalikesResponse" }, "example": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "results": [ { "id": "9659196", "firstName": "Sarah", "lastName": "Johnson" } ], "meta": { "returned": 1, "hasMore": true }, "billing": { "creditsCharged": 3, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "description": "dedupeSessionId is invalid or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupeSessionInvalidError" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v3/companies/lookalike": { "post": { "tags": [ "Lookalikes" ], "summary": "Company Lookalikes", "operationId": "getCompanyLookalikes", "description": "Find companies similar to a set of seed companies using AI-powered recommendations.\n\nProvide seed companies via domains or LinkedIn URLs. The API returns companies with similar size, industry, and profile.\n\n> **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`.\n\n**Pagination without duplicates:**\nOn 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.\n\nUse the `exclude` field to always filter out specific companies (e.g. existing customers or competitors).\n\nResults are lightweight previews. Use Enrich Companies with the returned `id` to get full firmographic data.\n\n> **Billing:** Charged per result via the `lookalikeCompany` action.\n\n> **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. See [Companies Tables](#tag/Companies-Tables).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookalikesRequest" }, "examples": { "firstRequest": { "summary": "First request - 6 seeds across both identifier types (server generates dedupeSessionId)", "value": { "seeds": { "domains": [ "sap.com", "oracle.com", "workday.com", "servicenow.com" ], "linkedinUrls": [ "https://www.linkedin.com/company/google", "https://www.linkedin.com/company/microsoft" ] }, "exclude": { "domains": [ "existingcustomer.com" ] }, "limit": 100 } }, "secondRequest": { "summary": "Second request - same 6 seeds, paginating with dedupeSessionId", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "seeds": { "domains": [ "sap.com", "oracle.com", "workday.com", "servicenow.com" ], "linkedinUrls": [ "https://www.linkedin.com/company/google", "https://www.linkedin.com/company/microsoft" ] }, "limit": 100 } } } } } }, "responses": { "200": { "description": "Successfully retrieved company lookalikes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookalikesResponse" }, "example": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "results": [ { "id": "12345", "name": "Marriott International", "domain": "marriott.com" } ], "meta": { "returned": 1, "hasMore": true }, "billing": { "creditsCharged": 3, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "description": "dedupeSessionId is invalid or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v3/contacts/buying-group": { "post": { "tags": [ "Buying Group" ], "summary": "Get Buying Group Contacts", "operationId": "getContactsBuyingGroup", "description": "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.\n\n**Personas:**\n- `decision_maker` - has budget or sign-off authority\n- `potential_champion` - likely internal advocate for the purchase\n- `end_user` - likely day-to-day user of the product\n\nPass `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).\n\nResults 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.\n\nUse Enrich Contacts with the returned contact `id` to reveal emails and phones.\n\n> **Billing:** Charged per contact returned via the `buyingGroupContact` action.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3BuyingGroupRequest" }, "example": { "companies": [ { "clientReferenceId": "comp-ref-1", "domain": "acme.com" }, { "clientReferenceId": "comp-ref-2", "id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" } ], "personas": [ "decision_maker", "potential_champion" ], "contactsLimit": 20 } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3BuyingGroupResponse" }, "example": { "requestId": "951d46da-24f9-4608-84bf-5e70a10bf851", "results": [ { "companyId": "v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP", "contacts": [ { "id": "v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ", "firstName": "Mohammed", "lastName": "Alam", "jobTitle": { "title": "RF/Analog IC Design Engineer", "departments": [ "Engineering & Technical" ], "seniority": "Non-Manager" }, "company": { "id": "v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP", "name": "Intel", "domain": "www.intel.com" }, "location": { "country": "United States", "state": "Arizona", "city": "Chandler" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/mohammed-alam-83759111" }, "has": [ "firstName", "lastName", "jobTitle", "company", "location", "socialLinks", "phones", "previousEmployment", "jobStartDate" ], "canReveal": [ { "field": "phones", "credits": 5 } ], "roles": [ "potential_champion" ], "score": 0.8872673511505127 } ] } ], "pagination": { "page": 0, "size": 100, "total": 1 }, "billing": { "creditsCharged": 1, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/tables": { "post": { "tags": [ "Contacts Tables" ], "summary": "Create Contacts Table", "operationId": "createContactsTable", "description": "Create a new, empty contacts table, optionally seeded with an initial list of contact IDs.\n\n> **Billing:** Free.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateRequest" }, "example": { "name": "VP Sales US Tech Q2", "visibility": "private", "owner": { "email": "user@example.com" }, "ids": [ "10042851", "10042852" ] } } } }, "responses": { "201": { "description": "Table created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/TableNameConflict" } } } }, "/v3/contacts/tables/list": { "post": { "tags": [ "Contacts Tables" ], "summary": "List Contacts Tables", "operationId": "listContactsTables", "description": "List contacts tables owned by the given user, plus any tables shared with the account.\n\n> **Billing:** Free.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableListRequest" }, "example": { "owner": { "email": "user@example.com" }, "page": 0, "size": 10, "status": "active" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/contacts/tables/columns": { "get": { "tags": [ "Contacts Tables" ], "summary": "Get Contacts Column Catalog", "operationId": "getContactsColumnCatalog", "description": "List every Lusha data column that can be added to a contacts table - 22 columns.\n\nNo request body and no parameters. Each entry returns the column's `category`,\n`displayName` (e.g. \"Job title\"), `columnKey` (e.g. `jobTitle` - the key you pass to\n[Add Columns to Contacts Table](#operation/addContactsTableColumns)), and `type`\n(`string` / `number` / `object`).\n\n> **Not the same as** [List Contacts Table Columns](#operation/listContactsTableColumns).\n> That endpoint lists the columns a *specific table already has*; this one lists\n> what's *available to add*.\n\n> **Billing:** Free - no credits charged.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnCatalogResponse" }, "example": { "data": [ { "category": "Contact details", "displayName": "Job title", "columnKey": "jobTitle", "type": "string" }, { "category": "Contact details", "displayName": "Seniority", "columnKey": "seniority", "type": "string" }, { "category": "Company", "displayName": "Company size", "columnKey": "companyEmployeeCount", "type": "number" }, { "category": "Company", "displayName": "Location", "columnKey": "location", "type": "object" } ], "billing": { "creditsCharged": 0, "resultsReturned": 22 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/contacts/tables/{table_id}": { "get": { "tags": [ "Contacts Tables" ], "summary": "Get Contacts Table", "operationId": "getContactsTable", "description": "Get a table's metadata and current processing status.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "patch": { "tags": [ "Contacts Tables" ], "summary": "Update Contacts Table", "operationId": "updateContactsTable", "description": "Rename a table, change its visibility, or reassign its owner. All fields except `owner` are optional - send only what changes.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateRequest" }, "example": { "name": "postman-renamed", "visibility": "shared", "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Table updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "delete": { "tags": [ "Contacts Tables" ], "summary": "Delete Contacts Table", "operationId": "deleteContactsTable", "description": "Permanently delete a table and all its data. This cannot be undone.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Table deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "tableId": { "type": "string", "example": "482910" }, "status": { "type": "string", "example": "deleted" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } } }, "/v3/contacts/tables/{table_id}/entities": { "get": { "tags": [ "Contacts Tables" ], "summary": "Get Contacts Table Entities", "operationId": "getContactsTableEntities", "description": "Read a page of rows in the table, with all column values and per-cell status.\n\n> **Billing:** Charged per row returned via `export_api`.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" }, { "name": "page", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 0 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesGetResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "post": { "tags": [ "Contacts Tables" ], "summary": "Add Entities to Contacts Table", "operationId": "addContactsTableEntities", "description": "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`.\n\nOptionally pass `companyIds` - one `lushaCompanyId` per contact, index-aligned with `entityIds` - to help pair company-level enrichment to the right company for each contact.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesAddRequest" }, "example": { "entityIds": [ "10042854", "10042855", "10042856" ], "companyIds": [ "16303253", "16303253", "12790225" ], "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Entities added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesAddResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "delete": { "tags": [ "Contacts Tables" ], "summary": "Remove Entities from Contacts Table", "operationId": "removeContactsTableEntities", "description": "Remove specific contact IDs from a table.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesRemoveRequest" }, "example": { "entityIds": [ "10042851", "10042852" ], "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Entities removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesRemoveResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } } }, "/v3/contacts/tables/{table_id}/columns": { "get": { "tags": [ "Contacts Tables" ], "summary": "List Contacts Table Columns", "operationId": "listContactsTableColumns", "description": "List the columns on a table, with type and aggregated per-cell status counts.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "post": { "tags": [ "Contacts Tables" ], "summary": "Add Columns to Contacts Table", "operationId": "addContactsTableColumns", "description": "Add up to 10 Lusha columns to a table in one call. Enrichment starts automatically on\n**all rows** in the table as soon as the columns are added.\n\n**Body** - either a list or a single key:\n- `columns: [{ \"columnKey\": \"jobTitle\" }, { \"columnKey\": \"seniority\" }]`\n- `columnKey: \"jobTitle\"` for a single column\n\nKeys come straight from\n[Get Contacts Column Catalog](#operation/getContactsColumnCatalog).\n\n**Partial success:** columns are handled independently. The response returns one entry\nper requested column with its own `status` (`added` / `failed`) and `columnId` - if one\ncolumn fails the rest still go through. The most common failure is the column already\nbeing on the table, in which case the existing `columnId` is returned, so the call is\nsafe to re-run.\n\n> **Billing:** Free today - credits aren't charged for adding columns yet.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsAddRequest" }, "examples": { "multipleColumns": { "summary": "Add several columns at once", "value": { "columns": [ { "columnKey": "jobTitle" }, { "columnKey": "seniority" }, { "columnKey": "workEmail" } ], "owner": { "email": "user@example.com" } } }, "singleColumn": { "summary": "Add a single column", "value": { "columnKey": "jobTitle", "owner": { "email": "user@example.com" } } } } } } }, "responses": { "200": { "description": "Columns processed. Returns one entry per requested column - check each entry's `status`, as some may have failed while others succeeded.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsAddResponse" }, "example": { "data": [ { "columnKey": "jobTitle", "columnId": "c_9f2a1b", "status": "added" }, { "columnKey": "seniority", "columnId": "c_44de07", "status": "added" }, { "columnKey": "workEmail", "columnId": "c_1c88fa", "status": "failed", "error": { "code": "COLUMN_ALREADY_EXISTS", "message": "Column already exists on this table" } } ], "billing": { "creditsCharged": 0, "resultsReturned": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } } }, "/v3/contacts/tables/{table_id}/columns/{column_id}": { "delete": { "tags": [ "Contacts Tables" ], "summary": "Remove Column from Contacts Table", "operationId": "removeContactsTableColumn", "description": "Remove a column and delete all of its cell data across the table. Default Lusha columns cannot be removed.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/ColumnIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Column removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "tableId": { "type": "string" }, "columnId": { "type": "string" }, "removed": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ColumnNotFound" } } } }, "/v3/contacts/tables/{table_id}/columns/{column_id}/run": { "post": { "tags": [ "Contacts Tables" ], "summary": "Run Column on Contacts Table", "operationId": "runContactsTableColumn", "description": "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.\n\n**`runScope` values:**\n- `all` - every row, including already-processed ones (re-runs / refreshes). Most expensive.\n- `missing` - only rows that have never been run for this column. Cheapest, safe to call repeatedly.\n- `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.\n\n> **Billing:** Charged per row processed, per the column's credit tier. Re-running with `all` charges again for rows that already have data.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/ColumnIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsRunRequest" }, "example": { "runScope": "specific", "entityIds": [ "10042851", "10042852" ], "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Column run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ColumnNotFound" } } } }, "/v3/companies/tables": { "post": { "tags": [ "Companies Tables" ], "summary": "Create Companies Table", "operationId": "createCompaniesTable", "description": "Create a new, empty companies table, optionally seeded with an initial list of company IDs.\n\n> **Billing:** Free.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateRequest" }, "example": { "name": "postman-companies", "visibility": "private", "owner": { "email": "user@example.com" } } } } }, "responses": { "201": { "description": "Table created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/TableNameConflict" } } } }, "/v3/companies/tables/list": { "post": { "tags": [ "Companies Tables" ], "summary": "List Companies Tables", "operationId": "listCompaniesTables", "description": "List companies tables owned by the given user, plus any tables shared with the account.\n\n> **Billing:** Free.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableListRequest" }, "example": { "owner": { "email": "user@example.com" }, "page": 0, "size": 10, "status": "active" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/tables/columns": { "get": { "tags": [ "Companies Tables" ], "summary": "Get Companies Column Catalog", "operationId": "getCompaniesColumnCatalog", "description": "List every Lusha data column that can be added to a companies table - 46 columns.\n\nNo request body and no parameters. Each entry returns the column's `category`,\n`displayName` (e.g. \"Industry\"), `columnKey` (e.g. `industry` - the key you pass to\n[Add Columns to Companies Table](#operation/addCompaniesTableColumns)), and `type`\n(`string` / `number` / `object`).\n\n> **Not the same as** [List Companies Table Columns](#operation/listCompaniesTableColumns).\n> That endpoint lists the columns a *specific table already has*; this one lists\n> what's *available to add*.\n\n> **Billing:** Free - no credits charged.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnCatalogResponse" }, "example": { "data": [ { "category": "Firmographics", "displayName": "Industry", "columnKey": "industry", "type": "string" }, { "category": "Firmographics", "displayName": "Year founded", "columnKey": "yearFounded", "type": "number" }, { "category": "Firmographics", "displayName": "Employees by department", "columnKey": "employeesByDepartment", "type": "object" }, { "category": "Funding", "displayName": "Total funding amount", "columnKey": "totalFundingAmount", "type": "number" } ], "billing": { "creditsCharged": 0, "resultsReturned": 46 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/tables/{table_id}": { "get": { "tags": [ "Companies Tables" ], "summary": "Get Companies Table", "operationId": "getCompaniesTable", "description": "Get a table's metadata and current processing status.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "patch": { "tags": [ "Companies Tables" ], "summary": "Update Companies Table", "operationId": "updateCompaniesTable", "description": "Rename a table, change its visibility, or reassign its owner. All fields except `owner` are optional - send only what changes.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateRequest" }, "example": { "name": "postman-renamed", "visibility": "shared", "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Table updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "delete": { "tags": [ "Companies Tables" ], "summary": "Delete Companies Table", "operationId": "deleteCompaniesTable", "description": "Permanently delete a table and all its data. This cannot be undone.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Table deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "tableId": { "type": "string", "example": "583021" }, "status": { "type": "string", "example": "deleted" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } } }, "/v3/companies/tables/{table_id}/entities": { "get": { "tags": [ "Companies Tables" ], "summary": "Get Companies Table Entities", "operationId": "getCompaniesTableEntities", "description": "Read a page of rows in the table, with all column values and per-cell status.\n\n> **Billing:** Charged per row returned via `export_api`.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" }, { "name": "page", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 0 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesGetResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "post": { "tags": [ "Companies Tables" ], "summary": "Add Entities to Companies Table", "operationId": "addCompaniesTableEntities", "description": "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`.\n\n> **Billing:** Charges `reveal_company` per newly-added company, deduped via row-count delta - duplicates and already-present companies aren't charged again.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesAddRequest" }, "example": { "entityIds": [ "30058211", "30058212" ], "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Entities added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesAddResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "delete": { "tags": [ "Companies Tables" ], "summary": "Remove Entities from Companies Table", "operationId": "removeCompaniesTableEntities", "description": "Remove specific company IDs from a table.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesRemoveRequest" }, "example": { "entityIds": [ "10117615" ], "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Entities removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesRemoveResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } } }, "/v3/companies/tables/{table_id}/columns": { "get": { "tags": [ "Companies Tables" ], "summary": "List Companies Table Columns", "operationId": "listCompaniesTableColumns", "description": "List the columns on a table, with type and aggregated per-cell status counts.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } }, "post": { "tags": [ "Companies Tables" ], "summary": "Add Columns to Companies Table", "operationId": "addCompaniesTableColumns", "description": "Add up to 10 Lusha columns to a table in one call. Enrichment starts automatically on\n**all rows** in the table as soon as the columns are added.\n\n**Body** - either a list or a single key:\n- `columns: [{ \"columnKey\": \"industry\" }, { \"columnKey\": \"yearFounded\" }]`\n- `columnKey: \"industry\"` for a single column\n\nKeys come straight from\n[Get Companies Column Catalog](#operation/getCompaniesColumnCatalog).\n\n**Partial success:** columns are handled independently. The response returns one entry\nper requested column with its own `status` (`added` / `failed`) and `columnId` - if one\ncolumn fails the rest still go through. The most common failure is the column already\nbeing on the table, in which case the existing `columnId` is returned, so the call is\nsafe to re-run.\n\n> **Billing:** Free today - credits aren't charged for adding columns yet.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsAddRequest" }, "examples": { "multipleColumns": { "summary": "Add several columns at once", "value": { "columns": [ { "columnKey": "industry" }, { "columnKey": "yearFounded" }, { "columnKey": "employeesByDepartment" } ], "owner": { "email": "user@example.com" } } }, "singleColumn": { "summary": "Add a single column", "value": { "columnKey": "industry", "owner": { "email": "user@example.com" } } } } } } }, "responses": { "200": { "description": "Columns processed. Returns one entry per requested column - check each entry's `status`, as some may have failed while others succeeded.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsAddResponse" }, "example": { "data": [ { "columnKey": "industry", "columnId": "c_31aa90", "status": "added" }, { "columnKey": "yearFounded", "columnId": "c_77b201", "status": "added" }, { "columnKey": "employeesByDepartment", "columnId": "c_0ce4d3", "status": "failed", "error": { "code": "COLUMN_ALREADY_EXISTS", "message": "Column already exists on this table" } } ], "billing": { "creditsCharged": 0, "resultsReturned": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TableNotFound" } } } }, "/v3/companies/tables/{table_id}/columns/{column_id}": { "delete": { "tags": [ "Companies Tables" ], "summary": "Remove Column from Companies Table", "operationId": "removeCompaniesTableColumn", "description": "Remove a column and delete all of its cell data across the table. Default Lusha columns cannot be removed.\n\n> **Billing:** Free.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/ColumnIdPath" }, { "$ref": "#/components/parameters/OwnerEmailQuery" } ], "responses": { "200": { "description": "Column removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "tableId": { "type": "string" }, "columnId": { "type": "string" }, "removed": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ColumnNotFound" } } } }, "/v3/companies/tables/{table_id}/columns/{column_id}/run": { "post": { "tags": [ "Companies Tables" ], "summary": "Run Column on Companies Table", "operationId": "runCompaniesTableColumn", "description": "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.\n\n**`runScope` values:**\n- `all` - every row, including already-processed ones (re-runs / refreshes). Most expensive.\n- `missing` - only rows that have never been run for this column. Cheapest, safe to call repeatedly.\n- `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.\n\n> **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.\n", "parameters": [ { "$ref": "#/components/parameters/TableIdPath" }, { "$ref": "#/components/parameters/ColumnIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsRunRequest" }, "example": { "runScope": "missing", "owner": { "email": "user@example.com" } } } } }, "responses": { "200": { "description": "Column run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ColumnNotFound" } } } }, "/v3/contacts/signals": { "post": { "tags": [ "Signals" ], "summary": "Contact Signals", "operationId": "getContactSignals", "description": "Retrieve signal events for a list of contacts - job changes and promotions.\n\nPass 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.\n\n> **Billing:** Charged per matched signal per result via the `showSignalsContact` action.\n\n> **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).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactSignalsRequest" }, "example": { "ids": [ "4389064624", "4389064654" ], "signalTypes": [ "allSignals" ], "startDate": "2025-01-01" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ContactSignalsResponse" }, "example": { "results": [ { "id": "115889", "companyChange": [ { "id": "115889", "signalDate": "2025-02-01", "previousCompany": "ZoomInfo", "newCompany": "Lusha" } ], "promotion": [] } ], "startDate": "2025-01-01", "endDate": "2025-03-01", "billing": { "creditsCharged": 1, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/companies/signals": { "post": { "tags": [ "Signals" ], "summary": "Company Signals", "operationId": "getCompanySignals", "description": "Retrieve signal events for a list of companies - hiring activity, headcount changes, web traffic, IT spend, and news.\n\nPass 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.\n\n> **Billing:** Charged per matched signal per result via the `showSignalsCompany` action.\n\n> **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).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompanySignalsRequest" }, "example": { "ids": [ "16303253" ], "signalTypes": [ "allSignals" ], "startDate": "2025-01-01", "maxResultsPerSignal": 10 } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3CompanySignalsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/signals/types": { "get": { "tags": [ "Signals" ], "summary": "Get Contact Signal Types", "operationId": "getContactSignalTypes", "description": "Returns the full list of supported signal types for contacts.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSignalTypesResponse" }, "example": { "signalTypes": [ "allSignals", "promotion", "companyChange" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/signals/types": { "get": { "tags": [ "Signals" ], "summary": "Get Company Signal Types", "operationId": "getCompanySignalTypes", "description": "Returns the full list of supported signal types for companies.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySignalTypesResponse" }, "example": { "signalTypes": [ "allSignals", "linkedinActivityIntent", "websiteTrafficDecrease", "websiteTrafficIncrease", "itSpendIncrease", "itSpendDecrease", "surgeInHiring", "headcountIncrease1m", "headcountIncrease3m", "headcountIncrease6m", "headcountIncrease12m", "headcountDecrease1m", "headcountDecrease3m", "headcountDecrease6m", "headcountDecrease12m", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/signals/filters": { "get": { "tags": [ "Signals" ], "summary": "Get Company Signal Filters (Discovery)", "operationId": "getCompanySignalFilters", "description": "Returns all available filter types for company signals and whether each requires a search query.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTypesDiscoveryResponse" }, "example": { "availableFilters": [ { "filterType": "newsEventTypes", "requiresQuery": false }, { "filterType": "hiringByDepartments", "requiresQuery": false }, { "filterType": "hiringByLocations", "requiresQuery": true }, { "filterType": "intentCategories", "requiresQuery": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/signals/filters/{filterType}": { "get": { "tags": [ "Signals" ], "summary": "Get Company Signal Filter Values", "operationId": "getCompanySignalFilterValues", "description": "Returns valid values for a single company signal filter type.\n\n| Filter type | Query required? |\n|---|---|\n| `newsEventTypes` | No |\n| `hiringByDepartments` | No |\n| `hiringByLocations` | Yes (2-256 chars) |\n| `intentCategories` | No - the `query` parameter is not supported for this filter type; passing one returns `400` |\n", "parameters": [ { "name": "filterType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "newsEventTypes", "hiringByDepartments", "hiringByLocations", "intentCategories" ] } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 256 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValuesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/signal-score": { "post": { "tags": [ "Signals" ], "summary": "Score Companies by Signal Activity", "operationId": "getCompanySignalScores", "description": "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.\n\nAccepts 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.\n\nEach result is one of:\n- A **scored entry** - `signalScore`, `signalTypes`, and `noActiveSignals`.\n- A **`NOT_FOUND`** entry - the company service could not resolve the supplied identifier.\n- A **`NO_SCORE`** entry - the company resolved, but the scoring engine returned nothing for it.\n\n> **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.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3SignalScoreCompaniesRequest" }, "example": { "companies": [ { "clientReferenceId": "ref-1", "id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" }, { "clientReferenceId": "ref-2", "domain": "www.microsoft.com" }, { "clientReferenceId": "ref-3", "name": "Apple" } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3SignalScoreCompaniesResponse" }, "example": { "requestId": "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a", "results": [ { "clientReferenceId": "ref-1", "id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345", "name": "Acme Corp", "domain": "www.acmecorp.io", "signalScore": 0.42, "signalTypes": [ "hiringSignalIncrease", "websiteVisit" ], "noActiveSignals": false }, { "clientReferenceId": "ref-2", "id": "v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01", "name": "Microsoft", "domain": "www.microsoft.com", "signalScore": 0, "signalTypes": [], "noActiveSignals": true }, { "clientReferenceId": "ref-3", "domain": "nope-xyz.com", "error": { "code": "NOT_FOUND", "message": "Company not found" } } ], "billing": { "creditsCharged": 2, "resultsReturned": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/signal-score": { "post": { "tags": [ "Signals" ], "summary": "Score Contacts by Signal Activity", "operationId": "getContactSignalScores", "description": "Score contacts by their active buying signals. Returns the aggregate Signal Score - a `[0, 1]` value - plus the active signal breakdown per contact.\n\nAccepts 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:\n- `id` (encrypted Lusha contact ID)\n- `linkedinUrl`\n- `email`\n- `firstName` + `lastName` + (`companyName` or `companyDomain`)\n\nEach result is one of:\n- A **scored entry** - `signalScore`, `signalTypes`, and `noActiveSignals`.\n- A **`NOT_FOUND`** entry - identity resolution failed for the supplied identifier.\n- A **`NO_SCORE`** entry - the contact resolved, but the scoring engine returned nothing for it.\n\n> **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.\n\n> **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.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3SignalScoreContactsRequest" }, "example": { "contacts": [ { "clientReferenceId": "ref-1", "id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" }, { "clientReferenceId": "ref-2", "linkedinUrl": "https://linkedin.com/in/johndoe" }, { "clientReferenceId": "ref-3", "firstName": "Jane", "lastName": "Doe", "companyDomain": "acme.com" } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3SignalScoreContactsResponse" }, "example": { "requestId": "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a", "results": [ { "clientReferenceId": "ref-1", "id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345", "fullName": "Jane Doe", "company": { "id": "v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01", "name": "Acme Corp", "domain": "acme.com" }, "signalScore": 0.3, "signalTypes": [ "promotion" ], "noActiveSignals": false }, { "clientReferenceId": "ref-2", "error": { "code": "NOT_FOUND", "message": "Contact not found" } } ], "billing": { "creditsCharged": 1, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/v3/companies/website-visits": { "post": { "tags": [ "Website Visits" ], "summary": "Get Website Visitors", "x-badges": [ { "name": "Beta", "color": "purple" } ], "operationId": "getWebsiteVisits", "description": "Returns companies ranked by website-visit signals for your tracked domains and date range.\n\nDomains 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.\n\n**Notes:**\n- Date range must be ≤ 3 months\n- If any requested domain is not configured for tracking, the entire request fails with `400`\n- `limit` accepts 1–150\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteVisitsRequest" }, "example": { "domains": [ "lusha.com", "google.com" ], "startDate": "2026-01-01", "endDate": "2026-03-18", "pagination": { "size": 25, "page": 0 }, "sort": { "by": "score", "order": "desc" }, "filters": { "scoreBands": [ "hot", "warm" ], "score": { "min": 50 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteVisitsResponse" }, "example": { "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "results": [ { "id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345", "name": "Lusha", "domain": "www.lusha.com", "industry": "Software Development", "employeeCount": { "min": 201, "max": 500 }, "location": { "city": "Tel Aviv", "country": "Israel", "countryIso2": "IL" }, "socialLinks": { "linkedin": "https://www.linkedin.com/company/lusha" }, "has": [ "competitors", "socialLinks" ], "canReveal": [ { "field": "competitors", "credits": 1 } ], "score": 87, "scoreBand": "hot", "totalSessions": 12, "uniqueVisitors": 5, "avgSessionMinutes": 4.2, "daysVisited": 8, "highIntentPageviews": 10, "daysSinceLastVisit": 6, "lastVisit": "2026-03-20", "visitorCountry": "US" } ], "pagination": { "size": 25, "page": 0, "total": 142 }, "billing": { "creditsCharged": 0, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/contacts/prospecting/filters": { "get": { "tags": [ "Filters" ], "summary": "Get Contact Filter Types (Discovery)", "operationId": "getContactFilterTypes", "description": "Returns all available filter types for contact prospecting and whether each requires a search query.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTypesDiscoveryResponse" }, "example": { "availableFilters": [ { "filterType": "locations", "requiresQuery": true }, { "filterType": "departments", "requiresQuery": false }, { "filterType": "seniority", "requiresQuery": false }, { "filterType": "countries", "requiresQuery": false }, { "filterType": "existingDataPoints", "requiresQuery": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/contacts/prospecting/filters/{filterType}": { "get": { "tags": [ "Filters" ], "summary": "Get Contact Filter Values", "operationId": "getContactFilterValues", "description": "Returns valid values for a single contact filter type.\n\n| Filter type | Query required? |\n|---|---|\n| `departments` | No |\n| `seniority` | No |\n| `existingDataPoints` | No |\n| `countries` | No |\n| `locations` | Yes (2-256 chars) |\n", "parameters": [ { "name": "filterType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "departments", "seniority", "existingDataPoints", "countries", "locations" ] } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 256 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValuesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/companies/prospecting/filters": { "get": { "tags": [ "Filters" ], "summary": "Get Company Filter Types (Discovery)", "operationId": "getCompanyFilterTypes", "description": "Returns all available filter types for company prospecting and whether each requires a search query.\n", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTypesDiscoveryResponse" }, "example": { "availableFilters": [ { "filterType": "names", "requiresQuery": true }, { "filterType": "technologies", "requiresQuery": true }, { "filterType": "industriesLabels", "requiresQuery": false }, { "filterType": "sizes", "requiresQuery": false }, { "filterType": "revenues", "requiresQuery": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v3/companies/prospecting/filters/{filterType}": { "get": { "tags": [ "Filters" ], "summary": "Get Company Filter Values", "operationId": "getCompanyFilterValues", "description": "Returns valid values for a single company filter type.\n\n| Filter type | Query required? |\n|---|---|\n| `sizes` | No |\n| `revenues` | No |\n| `sics` | No |\n| `naics` | No |\n| `intentTopics` | No |\n| `industriesLabels` | No |\n| `names` | Yes (2-256 chars) |\n| `technologies` | Yes (2-256 chars) |\n| `locations` | Yes (2-256 chars) |\n", "parameters": [ { "name": "filterType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "names", "sizes", "revenues", "locations", "sics", "naics", "industriesLabels", "intentTopics", "technologies" ] } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 256 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValuesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/subscriptions": { "post": { "tags": [ "Webhooks" ], "summary": "Create Subscription", "description": "Creates one or more webhook subscriptions for real-time signal notifications.\n\n**Delivery & Reliability:**\n- Webhooks are delivered with automatic retry on failures\n- Maximum 3 retry attempts with exponential backoff\n- Subscriptions auto-disable after max retries exceeded\n- All deliveries are logged in audit logs\n\n> **Note:** Your webhook endpoint must respond with a proper acknowledgment. \n See Client Response Format below for details.\n\n> **Limit:** Maximum 25 subscriptions per request\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions**\n\n---\n\n### Webhook Payload You'll Receive\n When a signal is triggered, this payload is sent to your webhook URL:\n```json\n {\n \"id\": \"f3b87e05-0402-4f3e-8e26-6a38fd0ad62c\",\n \"type\": \"promotion\",\n \"entityType\": \"contact\",\n \"entityId\": \"4158887495\",\n \"subscriptionId\": \"507f1f77bcf86cd799439011\",\n \"data\": {\n \"personId\": 4158887495,\n \"currentCompanyId\": 40823133,\n \"currentCompanyName\": \"OMG Hospitality Group LLC\",\n \"currentDomain\": \"omghospitalitygroup.com\",\n \"currentTitle\": \"Bartender\",\n \"currentDepartments\": [\n { \"id\": 7, \"value\": \"Other\" }\n ],\n \"previousCompanyName\": \"First Watch Restaurants\",\n \"previousDomain\": \"firstwatch.com\",\n \"signalDate\": \"2025-07-01\"\n },\n \"timestamp\": \"2026-01-14T16:16:35.841Z\",\n \"billing\": {\n \"creditsCharged\": 1\n }\n }\n ```\n **Example - Company News Signal:**\n ```json\n {\n \"id\": \"a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45\",\n \"type\": \"commercialActivityNews\",\n \"entityType\": \"company\",\n \"entityId\": \"33222678\",\n \"subscriptionId\": \"507f1f77bcf86cd799439011\",\n \"data\": {\n \"companyId\": \"33222678\",\n \"companyName\": \"Lusha\",\n \"domain\": \"lusha.com\",\n \"signalId\": \"1503910\",\n \"eventType\": \"partnership\",\n \"eventSummary\": \"Lusha announced a strategic partnership with Salesforce.\",\n \"articlePublishedDate\": \"2025-06-15\",\n \"articleTitle\": \"Lusha Partners with Salesforce\",\n \"articleHighlight\": \"The partnership enables Salesforce users to access Lusha data directly within their CRM.\",\n \"eventEffectiveDate\": \"2025-06-10\",\n \"articleUrl\": \"https://example.com/lusha-salesforce-partnership\"\n },\n \"timestamp\": \"2026-01-14T16:16:35.841Z\",\n \"billing\": {\n \"creditsCharged\": 1\n }\n }\n ```\n\n **Headers Included:**\n\n | Header | Description |\n |--------|-------------|\n | `X-Lusha-Signature` | HMAC-SHA256 signature for verification |\n | `X-Lusha-Timestamp` | Unix timestamp of the request |\n | `Content-Type` | application/json |\n | `User-Agent` | Lusha-Webhooks/1.0 |\n\n\n---\n⚠️ **Important:** Ensure your account has a webhook secret before creating subscriptions.\nCreate one via the [Regenerate Account Secret](#operation/regenerateAccountSecret) endpoint.\n\n---\n\n### Client Response Format (Required)\n\nWhen your webhook endpoint receives a delivery, it **must** acknowledge receipt with this response:\n\n **Required Response:**\n ````json\n {\n \"received\": true,\n \"timestamp\": \"2026-02-05T10:30:45.123Z\",\n \"webhookId\": \"f3b87e05-0402-4f3e-8e26-6a38fd0ad62c\"\n }\n ````\n\n
\nResponse Requirements\n\n | Requirement | Value |\n |-------------|-------|\n | **HTTP Status** | `201 Created` (recommended) or any `2xx` status |\n | **Content-Type** | `application/json` |\n | **Response Time** | Within 10 seconds |\n
\n\n\n
\nField Descriptions & Implementation Guide\n\n **Field Descriptions:**\n * `received` (boolean, required): Confirmation flag - must be `true`\n * `timestamp` (string, required): ISO 8601 timestamp of receipt\n * `webhookId` (string, required): Echo the `id` from webhook payload\n\n **Implementation Example:**\n ```javascript\n app.post('/webhook', async (req, res) => {\n // 1. Verify signature\n if (!verifyWebhookSignature(req)) {\n return res.status(401).json({ error: 'Invalid signature' });\n }\n \n // 2. Queue for async processing\n await queueWebhook(req.body);\n \n // 3. Acknowledge immediately\n res.status(201).json({\n received: true,\n timestamp: new Date().toISOString(),\n webhookId: req.body.id\n });\n ```\n\n **Important Notes:**\n * Return acknowledgment **before** heavy processing\n * Non-2xx responses trigger retry mechanism\n * After 3 failed retries, subscription is disabled\n\n
\n\n----\n", "operationId": "createSubscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" }, "examples": { "singleSubscription": { "summary": "Create a single subscription", "value": { "defaults": { "entityType": "contact", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha" }, "subscriptions": [ { "entityId": "123456", "name": "My Test Webhook" } ] } }, "multipleSubscriptions": { "summary": "Create multiple subscriptions with shared URL", "value": { "defaults": { "entityType": "contact", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha" }, "subscriptions": [ { "entityId": "123", "name": "Contact 123" }, { "entityId": "456", "name": "Contact 456" }, { "entityId": "789", "name": "Contact 789" } ] } }, "mixedEntityTypes": { "summary": "Mixed entity types with shared URL", "value": { "defaults": { "signalTypes": [ "promotion", "itSpendIncrease" ], "url": "https://example.com/webhooks/lusha" }, "subscriptions": [ { "entityType": "contact", "entityId": "123" }, { "entityType": "company", "entityId": "456" } ] } } } } } }, "responses": { "201": { "description": "Subscriptions created (full or partial success)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionResponse" }, "examples": { "allSuccessful": { "summary": "All subscriptions created successfully", "value": { "total": 3, "successful": 3, "failed": 0, "results": [ { "index": 0, "success": true, "subscription": { "id": "507f1f77bcf86cd799439011", "entityType": "contact", "entityId": "123", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha", "name": "Contact 123", "isActive": true, "createdAt": "2026-02-02T10:00:00.000Z", "updatedAt": "2026-02-02T10:00:00.000Z" } } ] } }, "partialSuccess": { "summary": "Some subscriptions failed (partial success)", "value": { "total": 3, "successful": 2, "failed": 1, "results": [ { "index": 0, "success": true, "subscription": { "id": "507f1f77bcf86cd799439011", "entityType": "contact", "entityId": "123", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha", "name": "Contact 123", "isActive": true, "createdAt": "2026-02-02T10:00:00.000Z", "updatedAt": "2026-02-02T10:00:00.000Z" } }, { "index": 1, "success": false, "error": { "code": "DUPLICATE_SUBSCRIPTION", "message": "Subscription already exists for entity type 'contact' with entity ID '456'" } } ] } } } } } }, "400": { "description": "Bad request - URL validation failed or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 400, "message": "Validation failed", "errors": [ "entityType must be one of: contact, company" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden - feature not available or limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 403, "message": "Maximum subscriptions limit reached for your account" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Webhooks" ], "summary": "List Subscriptions", "description": "Returns all webhook subscriptions for your account with pagination support.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/subscriptions**\n\n**Pagination:**\n- Results are sorted by `createdAt` in descending order (newest first)\n- Default limit: 10, max limit: 100\n- Use `offset` for pagination through large result sets\n\n> **Note:** The webhook `secret` is never returned in list responses for security.\n", "operationId": "listSubscriptions", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "example": 10 }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "List of subscriptions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionListResponse" }, "example": { "data": [ { "id": "507f1f77bcf86cd799439011", "entityType": "contact", "entityId": "123456", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhook", "name": "My Contact Webhook", "isActive": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ], "pagination": { "total": 25, "limit": 10, "offset": 0, "hasMore": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/subscriptions/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get Subscription by ID", "description": "Returns a single webhook subscription by ID.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/subscriptions/{id}**\n", "operationId": "getSubscriptionById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID", "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439011" } ], "responses": { "200": { "description": "Subscription retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionWithoutSecret" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update Subscription", "description": "Updates an existing webhook subscription. All fields are optional.\n\n*Endpoint*: **(PATCH) https://api.lusha.com/api/subscriptions/{id}**\n\n---\n**Reactivating Disabled Subscriptions:**\n\nWhen setting `isActive: true` on a previously disabled subscription, the system automatically:\n- Clears the `blockReason` field\n- Clears the `blockedAt` timestamp\n- Resets the retry counter\n\n**Regenerating Secrets:**\n\nSet `regenerateSecret: true` to generate a new webhook secret. The new secret:\n- Affects **all subscriptions** for your account\n- Is only shown once in the response\n- Immediately invalidates the old secret\n---\n", "operationId": "updateSubscription", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID", "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439011" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" }, "examples": { "disableSubscription": { "summary": "Disable a subscription", "value": { "isActive": false } }, "updateSignals": { "summary": "Change subscribed signals", "value": { "signalTypes": [ "promotion", "companyChange" ] } }, "regenerateSecret": { "summary": "Regenerate webhook secret", "value": { "regenerateSecret": true } }, "updateUrl": { "summary": "Update webhook URL", "value": { "url": "https://new-domain.com/webhooks/lusha" } } } } } }, "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/subscriptions/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test Subscription", "description": "Test a webhook subscription by sending a test signal. Supports three test modes.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/{id}/test**\n---\n**Test Modes:**\n- `direct` - Quick HTTP check only (validates URL responds correctly)\n- `kafka` - Fanout handler only (tests Kafka message processing)\n- `full` - Complete Kafka flow (default - end-to-end test)\n\n**Important Notes:**\n- Test deliveries do NOT consume credits\n- Test payloads use mock data\n- Useful for verifying webhook configuration before going live\n", "operationId": "testSubscription", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID", "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439011" }, { "name": "mode", "in": "query", "required": false, "description": "Test mode", "schema": { "type": "string", "enum": [ "direct", "kafka", "full" ], "default": "full" }, "example": "full" } ], "responses": { "200": { "description": "Test executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSubscriptionResponse" }, "example": { "subscriptionId": "507f1f77bcf86cd799439011", "subscriptionName": "My Test Webhook", "url": "https://example.com/webhook", "mode": "full", "flowCheck": { "success": true, "statusCode": 200, "durationMs": 150 }, "testPayload": { "entityType": "contact", "signalType": "promotion", "data": {} }, "isSuccess": true, "timestamp": "2024-01-01T00:00:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Subscription does not belong to your account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 403, "message": "Subscription does not belong to your account" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/subscriptions/delete": { "post": { "tags": [ "Webhooks" ], "summary": "Delete Subscriptions", "description": "Delete one or more webhook subscriptions. Returns detailed results for each deletion with partial success support.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/delete**\n\n---\n\n**Behavior:**\n- Each subscription is processed independently\n- Returns detailed results for each item including deleted subscription info\n- Invalid ID formats are gracefully handled and reported as NOT_FOUND\n- Duplicate IDs are automatically deduplicated\n- Deletion is permanent and cannot be undone\n", "operationId": "deleteSubscriptions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" }, "description": "Array of subscription IDs to delete", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] } } }, "examples": { "singleDelete": { "summary": "Delete a single subscription", "value": { "ids": [ "sub-123" ] } }, "multipleDelete": { "summary": "Delete multiple subscriptions", "value": { "ids": [ "sub-123", "sub-456", "sub-789" ] } } } } } }, "responses": { "200": { "description": "Delete operation completed (full or partial success)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSubscriptionResponse" }, "examples": { "allSuccessful": { "summary": "All subscriptions deleted successfully", "value": { "total": 3, "successful": 3, "failed": 0, "results": [ { "index": 0, "success": true, "subscription": { "id": "sub-123", "entityType": "contact", "entityId": "123", "name": "Contact Webhook" } } ] } }, "partialSuccess": { "summary": "Some deletions failed", "value": { "total": 3, "successful": 2, "failed": 1, "results": [ { "index": 0, "success": true, "subscription": { "id": "sub-123", "entityType": "contact", "entityId": "123", "name": "Contact Webhook" } }, { "index": 1, "success": false, "error": { "code": "NOT_FOUND", "message": "Subscription with id 'sub-456' not found" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/audit-logs": { "get": { "tags": [ "Webhooks" ], "summary": "Get Audit Logs", "description": "Retrieve webhook delivery logs for your account.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/audit-logs**\n\n**What's Logged:**\n- All webhook delivery attempts (success and failures)\n- HTTP status codes and response times\n- Error messages for failed deliveries\n- Delivery timestamps and duration metrics\n\n**Filtering:**\n- Filter by subscription ID to see logs for specific subscriptions\n- Filter by status to see only successes, failures, or permanent failures\n\n**Rate Limit:** 100 requests/minute per account\n\n> **Note:** Logs are retained for 90 days (successful) and 180 days (failed/DLQ)\n", "operationId": "getAuditLogs", "parameters": [ { "name": "subscriptionId", "in": "query", "required": false, "description": "Filter by subscription ID", "schema": { "type": "string" }, "example": "507f1f77bcf86cd799439011" }, { "name": "status", "in": "query", "required": false, "description": "Filter by delivery status", "schema": { "type": "string", "enum": [ "success", "failed", "permanent_failure" ] }, "example": "success" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "Audit logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogsResponse" }, "example": { "data": [ { "id": "log-123", "subscriptionId": "sub-123", "payloadId": "payload-456", "status": "success", "statusCode": 200, "url": "https://example.com/webhook", "deliveredAt": "2024-01-01T00:00:00.000Z", "durationMs": 150, "error": null } ], "pagination": { "total": 100, "limit": 50, "offset": 0, "hasMore": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/audit-logs/stats": { "get": { "tags": [ "Webhooks" ], "summary": "Get Audit Log Statistics", "description": "Get delivery statistics for your account.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/audit-logs/stats**\n", "operationId": "getAuditLogStats", "parameters": [ { "name": "subscriptionId", "in": "query", "required": false, "description": "Filter statistics by subscription ID", "schema": { "type": "string" }, "example": "sub-123" } ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogStatsResponse" }, "example": { "total": 1000, "success": 950, "failed": 50, "successRate": "95.00%" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/account/secret": { "get": { "tags": [ "Webhooks" ], "summary": "Get Account Secret", "description": "Retrieve the current account webhook secret.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/account/secret**\n", "operationId": "getAccountSecret", "responses": { "200": { "description": "Account secret retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "Current account webhook secret", "example": "whsec_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Account secret not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 404, "message": "Account secret not found. Please generate one first." } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/account/secret/regenerate": { "post": { "tags": [ "Webhooks" ], "summary": "Regenerate Account Secret", "description": "Regenerate the account webhook secret. Affects **all subscriptions** for the account.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/account/secret/regenerate**\n\n**Behavior:**\n- If a secret already exists: Replaces with new secret (old secret is invalidated)\n- If no secret exists: Creates new secret automatically\n\n**Important Notes:**\n- The secret is only shown once in the response. Store it securely.\n- This endpoint always succeeds (upsert operation)\n- Regenerating invalidates the old secret for **all subscriptions** (if one existed)\n- An account secret must exist before webhooks can be delivered\n", "operationId": "regenerateAccountSecret", "responses": { "200": { "description": "Account secret regenerated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "Newly generated account webhook secret (store securely - only shown once)", "example": "whsec_new_secret_here_abc123def456ghi789jkl012mno345" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/subscriptions/opt-out": { "post": { "tags": [ "Webhooks" ], "summary": "Create Opt-Out Subscription", "description": "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.).\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/opt-out**\n\n---\n\n**How it works:**\n- Create one opt-out subscription per account (scoped to `contact` entity type)\n- Lusha delivers a POST request to your URL whenever a contact opts out\n- The payload includes the contact identity, opt-out date, and the specific data points (emails and/or phones) that must be removed\n\n**Payload you'll receive:**\n```json\n{\n \"contactId\": \"987654321\",\n \"fullName\": \"Jane Doe\",\n \"companyName\": \"Acme Corp\",\n \"jobTitle\": \"Director of Product\",\n \"linkedinUrl\": \"https://www.linkedin.com/in/jane-doe\",\n \"contactOptOutDate\": \"2026-04-22 14:32:11.412\",\n \"contactExposureDate\": \"2025-08-03 09:15:47\",\n \"datapoints\": [\n { \"datapointId\": \"+14155550199\", \"datapointType\": \"phone\" },\n { \"datapointId\": \"jane.doe@acme.com\", \"datapointType\": \"email\" }\n ],\n \"partnerClientId\": \"acme-crm-tenant-42\"\n}\n```\n\n> **Important:** Signature verification applies the same way as standard webhook deliveries. See [Security & Verification](#tag/Webhooks) for details.\n\n> **Note:** Ensure your account has a webhook secret before creating this subscription. See [Regenerate Account Secret](#operation/regenerateAccountSecret).\n", "operationId": "createOptOutSubscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOptOutSubscriptionRequest" }, "example": { "entityType": "contact", "url": "https://example.com/webhook", "name": "Account opt-out webhook" } } } }, "responses": { "201": { "description": "Opt-out subscription created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOutSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden - feature not available or opt-out subscription already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 403, "message": "An opt-out subscription already exists for this account" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v3/account/usage": { "get": { "tags": [ "Account" ], "summary": "Get Account Usage", "operationId": "getAccountUsage", "description": "Returns a full snapshot of your account status:\n- **Credits** - total, used, and remaining for the current billing cycle\n- **Rate limits** - current usage and reset times for daily, hourly, and per-minute windows\n- **Plan** - your current plan category and renewal dates\n- **Pricing** - credit cost per action type across all public API endpoints\n\n> **Rate limit:** This endpoint is limited to 5 requests per minute.\n", "responses": { "200": { "description": "Successfully retrieved account usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsageResponse" }, "example": { "credits": { "total": 10000, "used": 1500, "remaining": 8500 }, "rateLimits": { "daily": { "limit": 5000, "used": 120, "remaining": 4880, "resetsAt": "2026-03-31T00:00:00.000Z" } }, "plan": { "category": "professional", "renewalType": "annual", "startDate": "2026-01-01T00:00:00.000Z", "endDate": "2027-01-01T00:00:00.000Z" }, "pricing": { "revealEmail": { "credits": 1, "perQuantity": 1 }, "revealPhone": { "credits": 5, "perQuantity": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v3/account/conversations/search": { "post": { "tags": [ "Conversations" ], "summary": "Search Conversations", "operationId": "searchConversations", "description": "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).\n\n**Two modes on the same contract:**\n- **Keyword mode** - supply `query` to rank conversations by transcript content. All other filters are ignored.\n- **Filter mode** - omit `query` and supply the structural filters.\n\nBoth modes return the same response shape. An empty body is valid and returns the first page of the account's conversations.\n\n**Validation notes:**\n- `companyDomains` matches on domain, not display name. Resolve a company name to a domain first (e.g. via [Search Companies](#operation/searchCompanies)).\n- `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`.\n- `pageSize` above 100 is rejected with `400` - it is not silently clamped.\n- `conversationIds` that don't exist, are still processing, or belong to another account are omitted from the response rather than erroring.\n\n> **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`).\n\n> **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\".\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ConversationsSearchRequest" }, "examples": { "keywordMode": { "summary": "Keyword mode (ranks by transcript content)", "value": { "query": "pricing objection", "page": 1, "pageSize": 25 } }, "filterMode": { "summary": "Filter mode (structural filters)", "value": { "dateFrom": "2026-01-01", "dateTo": "2026-03-31", "companyDomains": [ "acme.com" ], "contactNames": [ "Jane Doe" ], "meetingTitles": [ "Quarterly review" ], "page": 1, "pageSize": 25 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ConversationsSearchResponse" }, "example": { "requestId": "3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90", "conversations": [ { "id": "8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90", "title": "Acme <> Lusha - Quarterly review", "date": "2026-03-12", "startTime": "2026-03-12T14:00:00Z", "durationSeconds": 1830, "durationFormatted": "30m 30s", "meetingType": "discovery", "isExternal": true, "company": { "name": "Acme Inc", "domain": "acme.com" }, "participants": [ { "name": "Jane Doe", "email": "jane@acme.com", "role": "VP Sales", "isInternal": false }, { "name": "Sam Rep", "email": "sam@lusha.com", "role": "AE", "isInternal": true } ], "topicLabels": [ "pricing", "security" ], "summary": { "text": "The team walked through the pricing tiers.", "keyHighlights": [ "Budget confirmed for Q3" ], "actionItems": [ { "text": "Send the revised pricing sheet", "owner": "Sam Rep", "dueDate": "2026-03-19" } ], "nextSteps": [ "Schedule a technical deep dive" ], "risks": [ { "text": "Budget approval is still pending", "severity": "high" } ], "objections": [ { "text": "Price is above the current spend", "severity": null } ], "competition": [ { "name": "Competitor Inc", "context": "Mentioned as incumbent", "sentiment": "negative" } ] }, "coaching": { "overallScore": 68, "likelihoodOfSale": 45, "sections": [ { "section": "discovery", "score": 72, "whatHappened": "The rep opened with a clear agenda.", "whatToKeep": [ "Strong discovery questions" ], "whatToImprove": [ "Confirm the decision process earlier" ] } ], "notes": "Focus on quantifying impact." }, "chapters": [ { "index": 0, "title": "Introductions", "startTime": "00:00:00", "endTime": "00:04:12", "summary": "Participants introduced themselves." } ] } ], "page": { "page": 1, "pageSize": 25, "totalItems": 137, "totalPages": 6 }, "billing": { "creditsCharged": 1, "resultsReturned": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v3/account/conversations/{conversationId}/transcript": { "get": { "tags": [ "Conversations" ], "summary": "Get Conversation Transcript", "operationId": "getConversationTranscript", "description": "Returns the speaker-attributed, timestamped transcript of a single conversation. Get the `conversationId` from [Search Conversations](#operation/searchConversations).\n\nNo request body and no query parameters.\n\n> **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.\n\n> **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).\n", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Conversation identifier returned by Search Conversations.", "schema": { "type": "string" }, "example": "8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ConversationTranscriptResponse" }, "example": { "requestId": "3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90", "conversationId": "8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90", "segments": [ { "speaker": "Jane Doe", "side": "external", "text": "We need to understand the pricing tiers before we commit.", "startTime": "00:12:04", "endTime": "00:12:19" }, { "speaker": "Sam Rep", "side": "internal", "text": "Happy to walk you through them.", "startTime": "00:12:20", "endTime": "00:12:26" } ], "billing": { "creditsCharged": 1, "resultsReturned": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "api_key", "description": "Your Lusha API key. You can find this in your Lusha dashboard under API settings.\nInclude this key in the `api_key` header for all requests.\n" } }, "parameters": { "TableIdPath": { "name": "table_id", "in": "path", "required": true, "description": "The table's ID.", "schema": { "type": "string" }, "example": "482910" }, "ColumnIdPath": { "name": "column_id", "in": "path", "required": true, "description": "The column's ID.", "schema": { "type": "string" }, "example": "col_signals_funding" }, "OwnerEmailQuery": { "name": "email", "in": "query", "required": false, "description": "Email of the user making the request. Used to scope ownership/visibility checks on GET/DELETE calls, which cannot carry a body.", "schema": { "type": "string", "format": "email" }, "example": "user@example.com" } }, "responses": { "BadRequest": { "description": "Bad request - invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 400, "message": "Invalid request parameters" } } } }, "Unauthorized": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 401, "message": "Invalid API key" } } } }, "PaymentRequired": { "description": "Payment required - insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 402, "message": "Insufficient credits for this operation" } } } }, "Forbidden": { "description": "Forbidden - account inactive, V3 access not enabled, or plan does not include this feature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "accountInactive": { "summary": "Account inactive", "value": { "statusCode": 403, "message": "Your account is not active. Please reach out to support at support@lusha.com" } }, "v3NotEnabled": { "summary": "V3 access not enabled", "value": { "statusCode": 403, "message": "V3 API access is not enabled for your account" } } } } } }, "BadGateway": { "description": "Bad gateway - upstream identity resolution provider is unavailable. Retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 502, "message": "Identity resolution provider is temporarily unavailable. Retry with backoff." } } } }, "NotFound": { "description": "Not found - resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 404, "message": "Resource not found" } } } }, "TableNotFound": { "description": "Not found - table does not exist or is not accessible to this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 404, "message": "TABLE_NOT_FOUND: Table not found" } } } }, "ColumnNotFound": { "description": "Not found - column does not exist on the given table", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 404, "message": "COLUMN_NOT_FOUND: Column not found" } } } }, "TableNameConflict": { "description": "Conflict - a table with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 409, "message": "TABLE_NAME_CONFLICT: A table with this name already exists" } } } }, "TooManyRequests": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 429, "message": "Too many requests. Please wait before making another request." } } }, "headers": { "x-rate-limit-daily": { "description": "Total requests allowed per day", "schema": { "type": "integer" } }, "x-daily-requests-left": { "description": "Requests remaining in daily quota", "schema": { "type": "integer" } }, "x-rate-limit-hourly": { "description": "Total requests allowed per hour", "schema": { "type": "integer" } }, "x-hourly-requests-left": { "description": "Requests remaining in hourly quota", "schema": { "type": "integer" } }, "x-rate-limit-minute": { "description": "Total requests allowed per minute", "schema": { "type": "integer" } }, "x-minute-requests-left": { "description": "Requests remaining in current minute window", "schema": { "type": "integer" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 500, "message": "Internal server error. Please try again later." } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code", "example": 400 }, "message": { "type": "string", "description": "Error message", "example": "Validation failed" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Detailed error messages (optional, only for validation errors)", "example": [ "entityType must be one of: contact, company" ] } } }, "DedupeSessionInvalidError": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "DEDUPE_SESSION_INVALID" }, "message": { "type": "string", "example": "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run." } } }, "V3Billing": { "type": "object", "description": "Credit usage summary for a V3 API request", "properties": { "creditsCharged": { "type": "integer", "description": "Total credits charged for this request", "example": 3 }, "resultsReturned": { "type": "integer", "description": "Number of successful results returned", "example": 1 } } }, "V3SearchOptions": { "type": "object", "description": "Additional options for search requests", "properties": { "includePartialProfiles": { "type": "boolean", "description": "Include partial profiles in results", "example": true } } }, "V3CanRevealItem": { "type": "object", "description": "Indicates a data type that can be revealed and its credit cost", "properties": { "field": { "type": "string", "enum": [ "emails", "phones" ], "example": "emails" }, "credits": { "type": "integer", "description": "Credit cost (0 when already revealed for this account)", "example": 1 } } }, "V3ItemError": { "type": "object", "description": "Per-item error in a batch response", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "COMPLIANCE_RESTRICTED", "ENRICH_FAILED", "NO_SCORE" ], "example": "NOT_FOUND" }, "message": { "type": "string", "example": "Contact not found" } } }, "V3Location": { "type": "object", "description": "Location filter object used in prospecting requests", "properties": { "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "California" }, "country": { "type": "string", "example": "United States" }, "continent": { "type": "string", "example": "North America" }, "countryGrouping": { "type": "string", "example": "EMEA" }, "region": { "type": "string", "example": "California" }, "countryIso2": { "type": "string", "example": "US" } } }, "V3Range": { "type": "object", "description": "Numeric range filter", "properties": { "min": { "type": "integer", "minimum": 0, "example": 1 }, "max": { "type": "integer", "example": 1000 } } }, "V3PaginationRequest": { "type": "object", "required": [ "page", "size" ], "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0, "example": 0 }, "size": { "type": "integer", "minimum": 10, "maximum": 100, "default": 25, "example": 25 } } }, "V3PaginationResponse": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "size": { "type": "integer", "example": 25 }, "total": { "type": "integer" } } }, "V3ProspectingContactsPagination": { "type": "object", "description": "Pagination for Prospecting Contacts. Extends the standard pagination object with two optional fields describing the `total` count. Both keys are omitted when not returned.\n", "allOf": [ { "$ref": "#/components/schemas/V3PaginationResponse" }, { "type": "object", "properties": { "totalGuaranteed": { "type": "boolean", "description": "`true` when `total` is an exact count rather than an estimate.", "example": true }, "totalDescription": { "type": "string", "description": "Human-readable explanation of `total`.", "example": "Exact contact count (up to 2 per company)." } } } ] }, "TableOwner": { "type": "object", "description": "Identifies the user acting on the table, and resolves to a user on your account. Required on every table-route call when authenticating with an API key (there is no signed-in user) - omitting it returns `400`. Optional for OAuth/token callers, since the caller is already identified by the token; still accepted if you want to act on behalf of another owner.\n", "properties": { "email": { "type": "string", "format": "email", "description": "Must resolve to an existing user on the account tied to your API key.", "example": "user@example.com" } } }, "CellStatus": { "type": "string", "enum": [ "not_run", "processing", "success", "no_data", "failed" ], "description": "Current state of a single cell's data. `no_data` means the run succeeded but found nothing - distinct from `failed`, which means the run itself errored.\n" }, "RunScope": { "type": "string", "enum": [ "all", "missing", "specific" ], "description": "Controls which rows a column operation applies to. `all` re-runs every row, including already-processed ones. `missing` only runs rows that don't have a value for this column yet. `specific` requires `entityIds`.\n" }, "TableWrite": { "type": "object", "description": "Added to a Prospecting, Enrich, Signals, or Lookalike response when `tableId` is passed on the request. The primary response is unaffected even if the table write fails.\n", "properties": { "tableId": { "type": "string", "example": "482910" }, "added": { "type": "integer", "description": "Number of new entities added to the table by this call.", "example": 3 }, "alreadyPresent": { "type": "integer", "description": "Number of entities from this call that were already in the table.", "example": 2 }, "columnsCreated": { "type": "integer", "description": "Number of columns auto-created by this call (e.g. a Signals column created on first use).", "example": 0 }, "rowsProcessed": { "type": "integer", "description": "Number of rows the column-run touched as part of this call.", "example": 5 }, "rowsCharged": { "type": "integer", "description": "Number of those rows that incurred a credit charge.", "example": 5 }, "rowsAlreadyPaidInTable": { "type": "integer", "description": "Number of those rows that were already paid for in this table and were not re-charged.", "example": 0 }, "creditsCharged": { "type": "integer", "description": "Credits charged specifically for this table write.", "example": 0 } } }, "CreatedBy": { "type": "object", "description": "Where and by whom the table was created.", "properties": { "surface": { "type": "string", "enum": [ "api", "mcp", "workspace" ], "example": "api" }, "createdByUserId": { "type": "integer", "example": 12345 } } }, "AddedBy": { "type": "object", "description": "Where and by whom a row was added to the table.", "properties": { "surface": { "type": "string", "enum": [ "api", "mcp", "workspace" ], "example": "api" } } }, "TableMetadata": { "type": "object", "description": "TableDto - static metadata for a table.", "properties": { "tableId": { "type": "string", "example": "482910" }, "name": { "type": "string", "example": "VP Sales US Tech Q2" }, "entityType": { "type": "string", "enum": [ "contacts", "companies" ], "example": "contacts" }, "visibility": { "type": "string", "enum": [ "private", "shared" ], "example": "private" }, "status": { "type": "string", "enum": [ "active", "archived", "deleted" ], "description": "Lifecycle state. `active` and `archived` are filterable via the List Tables `status` field; `deleted` is not a filterable status.\n", "example": "active" }, "owner": { "$ref": "#/components/schemas/OwnerInfo" }, "createdBy": { "$ref": "#/components/schemas/CreatedBy" }, "workspaceUrl": { "type": "string", "example": "https://workspace.lusha.com/tables/482910" } } }, "OwnerInfo": { "type": "object", "description": "Resolved owner of the table. `id` is always present; `email` and `name` are resolved best-effort within the API key's account and may be omitted if resolution fails (in which case the object contains only `id`). Replaces the removed top-level `ownerId` field - this is a breaking change from the prior response shape.\n", "properties": { "id": { "type": "integer", "example": 12345 }, "email": { "type": "string", "format": "email", "example": "owner@lusha.com" }, "name": { "type": "string", "example": "Ada Lovelace" } } }, "TableStatusData": { "type": "object", "description": "Response payload for Get Table - TableDto fields plus live entity/column counts.", "allOf": [ { "$ref": "#/components/schemas/TableMetadata" }, { "type": "object", "properties": { "entityCount": { "type": "integer", "example": 5 }, "isProcessing": { "type": "boolean", "description": "Whether any column run is currently in progress on this table.", "example": false }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnSummary" } } } } ] }, "TableResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TableStatusData" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "TableCreateRequest": { "type": "object", "required": [ "name", "owner" ], "properties": { "name": { "type": "string", "example": "postman-companies" }, "visibility": { "type": "string", "enum": [ "private", "shared" ], "default": "private" }, "owner": { "$ref": "#/components/schemas/TableOwner" }, "ids": { "type": "array", "description": "Optional initial entity IDs to seed the table with.", "items": { "type": "string" }, "example": [ "10042851", "10042852" ] } } }, "TableUpdateRequest": { "type": "object", "required": [ "owner" ], "description": "`name`, `visibility`, and `archived` are all optional - send any subset; omitted fields stay unchanged. Sending none of them is a no-op. A partial update re-reads the persisted table first, so fields you don't send are never clobbered.\n", "properties": { "name": { "type": "string", "example": "renamed" }, "visibility": { "type": "string", "enum": [ "private", "shared" ], "example": "shared" }, "archived": { "type": "boolean", "description": "Set `true` to archive the table (hides it from default List Tables results), `false` to restore it.", "example": true }, "owner": { "$ref": "#/components/schemas/TableOwner" } } }, "TableListRequest": { "type": "object", "required": [ "owner" ], "properties": { "owner": { "$ref": "#/components/schemas/TableOwner" }, "page": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 }, "size": { "type": "integer", "default": 100 }, "name": { "type": "string", "description": "Optional filter - matches tables whose name contains this text.", "example": "Q3" }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "`deleted` is not a filterable status." } } }, "TableListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TableMetadata" } }, "pagination": { "$ref": "#/components/schemas/V3PaginationResponse" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "EntitiesAddRequest": { "type": "object", "required": [ "entityIds", "owner" ], "properties": { "entityIds": { "type": "array", "items": { "type": "string" }, "maxItems": 500, "description": "Lusha IDs as strings - `personId` for contacts, `lushaCompanyId` for companies. Accepts either the encrypted token (`v{N}.…`, as returned by Search/Enrich/Get Entities) or the legacy numeric ID. An ID that is neither a valid token nor numeric returns `400`.\n", "example": [ "10042854", "10042855", "10042856" ] }, "companyIds": { "type": "array", "items": { "type": "string" }, "description": "Contacts tables only. One `lushaCompanyId` per contact (encrypted token or numeric), index-aligned with `entityIds`, to help pair company-level enrichment to the right company for each contact. Ignored on companies tables.\n", "example": [ "16303253", "16303253", "12790225" ] }, "owner": { "$ref": "#/components/schemas/TableOwner" } } }, "EntitiesAddResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer", "example": 20 }, "alreadyPresent": { "type": "integer", "example": 5 }, "invalidIds": { "type": "array", "description": "IDs that couldn't be resolved. Not an error - the call still returns `200`.", "items": { "type": "string" }, "example": [] }, "addedBy": { "$ref": "#/components/schemas/AddedBy" } } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "EntitiesRemoveRequest": { "type": "object", "required": [ "entityIds", "owner" ], "properties": { "entityIds": { "type": "array", "items": { "type": "string" }, "description": "Accepts either the encrypted token (`v{N}.…`, as returned by Get Entities) or the legacy numeric ID. Unresolved IDs are echoed back in `invalidIds` in the exact form you sent them.\n", "example": [ "10042851", "10042852" ] }, "owner": { "$ref": "#/components/schemas/TableOwner" } } }, "EntitiesRemoveResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "removed": { "type": "integer", "example": 10 }, "invalidIds": { "type": "array", "items": { "type": "string" }, "example": [] } } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "EntityColumnValue": { "type": "object", "description": "One column's value on a single row, as returned by Get Entities. This shape is a passthrough from the underlying Workspace service - the fields shown here (`id`, `name`, `type`, `sourceType`, `value`, `status`) are representative, not an exhaustive schema.\n", "properties": { "id": { "type": "string", "example": "f8c1a2b3" }, "name": { "type": "string", "example": "company_name" }, "type": { "type": "string", "example": "string" }, "sourceType": { "type": "string", "example": "lusha" }, "value": { "nullable": true, "description": "The cell's data. Shape depends on the column type.", "example": "Google" }, "status": { "$ref": "#/components/schemas/CellStatus" } } }, "TableEntity": { "type": "object", "description": "A single row. `id` is the **encrypted** Lusha ID (`v{N}.…`) - `personId` for contacts, `lushaCompanyId` for companies - in the same format used across V3, so it round-trips directly into Add Entities, Remove Entities, and Enrich. Internal fields (`accountId`, `companyLid`, `lushaCompanyId`, `personId`, `companyDetails`) are not returned. Remaining per-row fields under `columns` are owned by the Workspace service; this shape is representative, not an exhaustive schema.\n", "properties": { "id": { "type": "string", "description": "Encrypted Lusha ID.", "example": "v1.aB3kZ9example" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/EntityColumnValue" } } } }, "EntitiesGetResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TableEntity" } }, "pagination": { "$ref": "#/components/schemas/V3PaginationResponse" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ColumnSummary": { "type": "object", "description": "ColumnDto - a column's definition plus aggregated per-cell status counts.", "properties": { "columnId": { "type": "string", "example": "c1" }, "name": { "type": "string", "example": "Job title" }, "type": { "type": "string", "enum": [ "lusha", "crm", "signal", "ai", "score" ], "example": "lusha" }, "key": { "type": "string", "nullable": true, "example": "jobTitle" }, "isDefault": { "type": "boolean", "description": "Default Lusha columns cannot be removed.", "example": false }, "addedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "rowsNotRun": { "type": "integer" }, "rowsProcessing": { "type": "integer" }, "rowsSuccess": { "type": "integer" }, "rowsNoData": { "type": "integer" }, "rowsFailed": { "type": "integer" } } }, "ColumnsListResponse": { "type": "object", "description": "Response for List Columns - `data` is a bare array of ColumnDto.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnSummary" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ColumnCatalogItem": { "type": "object", "description": "One Lusha data column available to add to a table. Returned by the column catalog endpoints.\n", "properties": { "category": { "type": "string", "description": "Grouping the column belongs to in the catalog and in the Workspace UI.", "example": "Contact details" }, "displayName": { "type": "string", "description": "Human-readable column name, as shown on the table.", "example": "Job title" }, "columnKey": { "type": "string", "description": "Stable machine key for this column. Pass this value as `columnKey` when adding the column to a table.\n", "example": "jobTitle" }, "type": { "type": "string", "enum": [ "string", "number", "object" ], "description": "Data type of the values this column produces.", "example": "string" } } }, "ColumnCatalogResponse": { "type": "object", "description": "The full catalog of Lusha columns available for this entity type - 22 for contacts, 46 for companies.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnCatalogItem" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ColumnsAddItem": { "type": "object", "required": [ "columnKey" ], "properties": { "columnKey": { "type": "string", "description": "A `columnKey` from the column catalog endpoint.", "example": "jobTitle" } } }, "ColumnsAddRequest": { "type": "object", "description": "Supply either `columns` (up to 10 entries) or a single `columnKey` - not both. Sending neither returns `400`.\n", "properties": { "columns": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Up to 10 Lusha columns to add in one call.", "items": { "$ref": "#/components/schemas/ColumnsAddItem" } }, "columnKey": { "type": "string", "description": "Shorthand for adding exactly one column.", "example": "jobTitle" }, "owner": { "$ref": "#/components/schemas/TableOwner" } }, "oneOf": [ { "required": [ "columns" ] }, { "required": [ "columnKey" ] } ] }, "ColumnsAddItemError": { "type": "object", "description": "Present only when `status` is `failed`.", "properties": { "code": { "type": "string", "enum": [ "COLUMN_ALREADY_EXISTS", "COLUMN_KEY_NOT_FOUND", "COLUMN_LIMIT_EXCEEDED", "UNKNOWN_ERROR" ], "description": "`COLUMN_ALREADY_EXISTS` is the most common - the column is already on the table, and the existing `columnId` is returned alongside it.\n", "example": "COLUMN_ALREADY_EXISTS" }, "message": { "type": "string", "example": "Column already exists on this table" } } }, "ColumnsAddResultItem": { "type": "object", "description": "Outcome for a single requested column. Columns are processed independently - a `failed` entry does not prevent the others from being added.\n", "properties": { "columnKey": { "type": "string", "example": "jobTitle" }, "columnId": { "type": "string", "description": "ID of the column on this table. Present on `added`, and also on a `COLUMN_ALREADY_EXISTS` failure - in that case it's the ID of the column that was already there, so the request can simply be re-run.\n", "example": "c_9f2a1b" }, "status": { "type": "string", "enum": [ "added", "failed" ], "example": "added" }, "error": { "$ref": "#/components/schemas/ColumnsAddItemError" } } }, "ColumnsAddResponse": { "type": "object", "description": "One entry per requested column. Enrichment runs asynchronously on every row in the table for each successfully added column - poll Get Table for `isProcessing` and per-column row-status counts, then read the values via Get Table Entities.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnsAddResultItem" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ColumnsRunRequest": { "type": "object", "required": [ "runScope", "owner" ], "properties": { "runScope": { "$ref": "#/components/schemas/RunScope" }, "entityIds": { "type": "array", "items": { "type": "string" }, "description": "Required when `runScope` is `specific`." }, "owner": { "$ref": "#/components/schemas/TableOwner" } } }, "ColumnsRunResponse": { "type": "object", "description": "Run is asynchronous - this response confirms the run was accepted. Poll Get Table for per-column row-status counts to know when it's finished.\n", "properties": { "data": { "type": "object", "properties": { "columnId": { "type": "string", "example": "c1" }, "runScope": { "$ref": "#/components/schemas/RunScope" }, "status": { "type": "string", "example": "processing" } } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ContactSearchItem": { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "my-ref-1" }, "id": { "type": "string", "example": "12345" }, "linkedinUrl": { "type": "string", "example": "https://www.linkedin.com/in/orit-shilvock-6243bb5" }, "email": { "type": "string", "format": "email", "example": "orit.shilvock@lusha.com" }, "firstName": { "type": "string", "example": "Orit" }, "lastName": { "type": "string", "example": "Shilvock" }, "companyName": { "type": "string", "example": "Lusha" }, "companyDomain": { "type": "string", "example": "lusha.com" } } }, "V3ContactSignalsDto": { "type": "object", "required": [ "types" ], "properties": { "types": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] }, "example": [ "promotion", "companyChange" ] }, "startDate": { "type": "string", "format": "date", "example": "2025-01-01" }, "maxResultsPerSignal": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 } } }, "V3ContactPreview": { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "my-ref-1" }, "id": { "type": "string", "example": "4389064704" }, "firstName": { "type": "string", "example": "Orit" }, "lastName": { "type": "string", "example": "Shilvock" }, "jobTitle": { "type": "object", "properties": { "title": { "type": "string", "example": "Vice President of Partnerships" }, "departments": { "type": "array", "items": { "type": "string" }, "example": [ "Business Development" ] }, "seniority": { "type": "string", "example": "Vice President" } } }, "company": { "type": "object", "properties": { "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "www.lusha.com" } } }, "location": { "type": "object", "properties": { "country": { "type": "string", "example": "Israel" }, "state": { "type": "string", "example": "Tel Aviv District" }, "city": { "type": "string", "example": "Tel Aviv" } } }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/orit-shilvock-6243bb5" } } }, "has": { "type": "array", "items": { "type": "string" }, "example": [ "firstName", "lastName", "jobTitle", "location", "socialLinks", "emails" ] }, "canReveal": { "type": "array", "items": { "$ref": "#/components/schemas/V3CanRevealItem" } }, "signalTypes": { "type": "array", "items": { "type": "string" }, "example": [ "promotion", "companyChange" ] }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3EmailAddress": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "orit.shilvock@lusha.com" }, "type": { "type": "string", "enum": [ "work", "private", "unknown" ], "example": "work" }, "confidence": { "type": "string", "nullable": true, "example": "A+" }, "updateDate": { "type": "string", "format": "date", "example": "2026-04-23" } } }, "V3PhoneNumber": { "type": "object", "properties": { "number": { "type": "string", "example": "+14155551234" }, "type": { "type": "string", "enum": [ "mobile", "direct", "work", "unknown" ], "example": "mobile" }, "doNotCall": { "type": "boolean", "example": false }, "updateDate": { "type": "string", "format": "date", "example": "2026-04-23" } } }, "V3ContactTag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "example": "#FF5733" } } }, "V3EnrichedContactCompanyRef": { "type": "object", "properties": { "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "www.lusha.com" }, "industry": { "type": "string", "example": "Technology, Information & Media" } } }, "V3EnrichedContact": { "type": "object", "properties": { "id": { "type": "string", "example": "4389064704" }, "firstName": { "type": "string", "example": "Orit" }, "lastName": { "type": "string", "example": "Shilvock" }, "fullName": { "type": "string", "example": "Orit Shilvock" }, "jobTitle": { "type": "object", "properties": { "title": { "type": "string", "example": "Vice President of Partnerships" }, "departments": { "type": "array", "items": { "type": "string" }, "example": [ "Business Development" ] }, "seniority": { "type": "string", "example": "Vice President" } } }, "location": { "type": "object", "properties": { "country": { "type": "string", "example": "Israel" }, "countryIso2": { "type": "string", "example": "IL" }, "state": { "type": "string", "example": "Tel Aviv District" }, "city": { "type": "string", "example": "Tel Aviv" }, "continent": { "type": "string", "example": "Asia" }, "coordinates": { "type": "array", "items": { "type": "number" }, "example": [ 34.78057098388672, 32.08087921142578 ] }, "isEuContact": { "type": "boolean", "example": false } } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/V3ContactTag" } }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/V3EmailAddress" } }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/V3PhoneNumber" } }, "company": { "$ref": "#/components/schemas/V3EnrichedContactCompanyRef" }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/orit-shilvock-6243bb5" }, "xUrl": { "type": "string", "example": "https://twitter.com/lushaofficial" } } }, "previousEmployment": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" } } }, "jobTitle": { "type": "object", "properties": { "title": { "type": "string" }, "departments": { "type": "array", "items": { "type": "string" } }, "seniority": { "type": "string" } } } } } }, "updateDate": { "type": "string", "format": "date", "example": "2026-04-23" }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3SearchAndEnrichContactResult": { "allOf": [ { "$ref": "#/components/schemas/V3EnrichedContact" }, { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "my-ref-1" } } } ] }, "WebsiteVisitsIntRange": { "type": "object", "description": "Integer range filter (non-negative)", "properties": { "min": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 0 } } }, "WebsiteVisitsFloatRange": { "type": "object", "description": "Float range filter (non-negative)", "properties": { "min": { "type": "number", "minimum": 0 }, "max": { "type": "number", "minimum": 0 } } }, "WebsiteVisitsFilters": { "type": "object", "properties": { "scoreBands": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "hot" ] }, "description": "Restrict to specific score bands.", "example": [ "hot", "warm" ] }, "visitorCountries": { "type": "object", "description": "ISO 3166-1 alpha-2 country code filters.", "properties": { "include": { "type": "array", "items": { "type": "string" }, "example": [ "US", "GB" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "example": [ "CN" ] } } }, "score": { "allOf": [ { "$ref": "#/components/schemas/WebsiteVisitsIntRange" } ], "description": "Score range (1–100)." }, "totalSessions": { "$ref": "#/components/schemas/WebsiteVisitsIntRange" }, "avgSessionMinutes": { "$ref": "#/components/schemas/WebsiteVisitsFloatRange" }, "uniqueVisitors": { "$ref": "#/components/schemas/WebsiteVisitsIntRange" }, "daysVisited": { "$ref": "#/components/schemas/WebsiteVisitsIntRange" }, "highIntentPageviews": { "$ref": "#/components/schemas/WebsiteVisitsIntRange" }, "daysSinceLastVisit": { "$ref": "#/components/schemas/WebsiteVisitsIntRange" } } }, "WebsiteVisitsRequest": { "type": "object", "required": [ "domains", "startDate", "endDate", "pagination" ], "properties": { "domains": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Domains configured for tracking in the Lusha dashboard.", "example": [ "lusha.com", "google.com" ] }, "startDate": { "type": "string", "format": "date", "description": "Window start date (YYYY-MM-DD).", "example": "2026-01-01" }, "endDate": { "type": "string", "format": "date", "description": "Window end date (YYYY-MM-DD). Range must be ≤ 3 months.", "example": "2026-03-18" }, "pagination": { "type": "object", "required": [ "page", "size" ], "properties": { "size": { "type": "integer", "minimum": 1, "maximum": 150, "example": 25 }, "page": { "type": "integer", "minimum": 0, "example": 0 } } }, "sort": { "type": "object", "properties": { "by": { "type": "string", "description": "Field to sort by (e.g. `score`).", "example": "score" }, "order": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } } }, "filters": { "$ref": "#/components/schemas/WebsiteVisitsFilters" } } }, "WebsiteVisitsCompanyResult": { "allOf": [ { "$ref": "#/components/schemas/V3CompanyPreview" }, { "type": "object", "description": "Firmographic preview plus behavioral visit metrics.", "properties": { "score": { "type": "number", "description": "Display score (0–100).", "example": 87 }, "scoreBand": { "type": "string", "enum": [ "cold", "warm", "hot" ], "description": "Qualitative score band.", "example": "hot" }, "totalSessions": { "type": "number", "description": "Total sessions in the window.", "example": 12 }, "uniqueVisitors": { "type": "number", "description": "Distinct visitors in the window.", "example": 5 }, "avgSessionMinutes": { "type": "number", "description": "Average session length in minutes.", "example": 4.2 }, "daysVisited": { "type": "number", "description": "Distinct days with activity.", "example": 8 }, "highIntentPageviews": { "type": "number", "description": "High-intent pageviews in the window.", "example": 10 }, "daysSinceLastVisit": { "type": "number", "description": "Days since the most recent visit.", "example": 6 }, "lastVisit": { "type": "string", "format": "date", "description": "Date of the last visit in the window.", "example": "2026-03-20" }, "visitorCountry": { "type": "string", "description": "Primary visitor country (ISO 3166-1 alpha-2). Omitted if unavailable.", "example": "US" } } } ] }, "WebsiteVisitsPagination": { "type": "object", "required": [ "page", "size", "total" ], "properties": { "size": { "type": "integer", "example": 25 }, "page": { "type": "integer", "example": 0 }, "total": { "type": "integer", "description": "Total results across all pages.", "example": 142 } } }, "WebsiteVisitsResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteVisitsCompanyResult" } }, "pagination": { "$ref": "#/components/schemas/WebsiteVisitsPagination" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3CompanySearchItem": { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "comp-ref-1" }, "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "V3CompanySignalsDto": { "type": "object", "required": [ "types" ], "properties": { "types": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "linkedinActivityIntent", "websiteTrafficDecrease", "websiteTrafficIncrease", "itSpendIncrease", "itSpendDecrease", "surgeInHiring", "headcountIncrease1m", "headcountIncrease3m", "headcountIncrease6m", "headcountIncrease12m", "headcountDecrease1m", "headcountDecrease3m", "headcountDecrease6m", "headcountDecrease12m", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": [ "headcountIncrease3m", "surgeInHiring" ] }, "startDate": { "type": "string", "format": "date", "example": "2025-01-01" }, "maxResultsPerSignal": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 } } }, "V3CompanyPreview": { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "comp-ref-1" }, "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "www.lusha.com" }, "employeeCount": { "type": "object", "properties": { "exact": { "type": "integer", "example": 364 }, "min": { "type": "integer", "example": 201 }, "max": { "type": "integer", "example": 500 } } }, "industry": { "type": "string", "example": "Technology, Information & Media" }, "location": { "type": "object", "properties": { "city": { "type": "string", "example": "London" }, "state": { "type": "string", "example": "England" }, "stateCode": { "type": "string", "description": "Free field. ISO/postal state or region code, when available.", "example": "MA" }, "country": { "type": "string", "example": "United Kingdom" }, "countryIso2": { "type": "string", "example": "GB" }, "continent": { "type": "string", "example": "Europe" } } }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/company/lushadata" } } }, "has": { "type": "array", "items": { "type": "string" }, "description": "Available data points that can be revealed via Enrich Companies. Includes base firmographic fields plus new revealable fields: employeesByDepartment, employeesByLocation, employeesBySeniority, competitors, businessModel, phones, emails, keywords, socialLinks, estimatedAnnualItSpend, monthlyWebsiteTraffic, openJobs, directParent, ultimateParent.\n", "example": [ "alternativeName", "alternativeDomains", "description", "companyType", "yearFounded", "subIndustry", "specialities", "sicCodes", "naicsCodes", "additionalLocations", "linkedinFollowers", "popularityTier", "logoUrl", "employeesByDepartment", "employeesByLocation", "employeesBySeniority", "competitors", "businessModel", "phones", "emails", "keywords", "socialLinks", "estimatedAnnualItSpend", "monthlyWebsiteTraffic", "openJobs", "directParent", "ultimateParent" ] }, "canReveal": { "type": "array", "description": "Data fields that can be revealed via Enrich Companies, with the credit cost per field. A cost of 0 means the field has already been revealed for this account.\n", "items": { "$ref": "#/components/schemas/V3CanRevealItem" }, "example": [ { "field": "employeesByDepartment", "credits": 1 }, { "field": "employeesByLocation", "credits": 1 }, { "field": "employeesBySeniority", "credits": 1 }, { "field": "competitors", "credits": 1 }, { "field": "intent", "credits": 0 }, { "field": "estimatedAnnualItSpend", "credits": 1 }, { "field": "monthlyWebsiteTraffic", "credits": 1 }, { "field": "openJobsTotal", "credits": 1 }, { "field": "openJobsByDepartment", "credits": 1 }, { "field": "openJobsByLocation", "credits": 1 }, { "field": "openJobsBySeniority", "credits": 1 }, { "field": "directParent", "credits": 1 }, { "field": "ultimateParent", "credits": 1 } ] }, "signalTypes": { "type": "array", "items": { "type": "string" }, "example": [ "headcountIncrease3m" ] }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3CompanyParent": { "type": "object", "description": "A company in an ownership tree, returned by the `directParent` and `ultimateParent` premium reveal fields. Pass `lushaCompanyId` back to Enrich Companies to retrieve the parent's full firmographic profile.", "properties": { "lushaCompanyId": { "type": "string", "description": "Lusha company ID of the parent. Use this with Enrich Companies to look up the parent.", "example": "v1.QrSt..." }, "name": { "type": "string", "example": "Constellation Software Inc." }, "domain": { "type": "string", "example": "csisoftware.com" }, "hqCountry": { "type": "string", "description": "Country of the parent's headquarters. Not always present.", "example": "Canada" } } }, "V3CompanyLocation": { "type": "object", "properties": { "city": { "type": "string", "example": "London" }, "state": { "type": "string", "example": "England" }, "stateCode": { "type": "string", "description": "Free field. ISO/postal state or region code, when available.", "example": "MA" }, "country": { "type": "string", "example": "United Kingdom" }, "countryIso2": { "type": "string", "example": "GB" }, "continent": { "type": "string", "example": "Europe" }, "zipCode": { "type": "string", "description": "Postal/ZIP code (present on HQ location when available)", "example": "80904" } } }, "V3SicCode": { "type": "object", "properties": { "code": { "type": "integer", "example": 7371 }, "description": { "type": "string", "example": "Custom computer programming services" } } }, "V3NaicsCode": { "type": "object", "properties": { "code": { "type": "integer", "example": 541511 }, "description": { "type": "string", "example": "Custom Computer Programming Services" } } }, "V3OpenJobsByDepartment": { "type": "object", "description": "Open job posting count for a single department.", "properties": { "department": { "type": "string", "example": "Engineering" }, "count": { "type": "integer", "example": 21 } } }, "V3OpenJobsByLocation": { "type": "object", "description": "Open job posting count for a single location.", "properties": { "location": { "type": "string", "example": "United States" }, "count": { "type": "integer", "example": 12 } } }, "V3OpenJobsBySeniority": { "type": "object", "description": "Open job posting count for a single seniority level.", "properties": { "seniority": { "type": "string", "example": "Manager" }, "count": { "type": "integer", "example": 5 } } }, "V3OpenJobs": { "type": "object", "description": "Open job posting counts. Each sub-field is revealed independently in Enrich Companies via `reveal: [\"openJobsTotal\", \"openJobsByDepartment\", \"openJobsByLocation\", \"openJobsBySeniority\"]`. A sub-field is present only when its matching token was requested in `reveal` and data exists for it; sub-fields that weren't requested, or that have no data, are omitted. Department, location, and seniority values use the same vocabularies as the existing prospecting filters.\n", "nullable": true, "properties": { "total": { "type": "integer", "description": "Total number of open job postings. Revealed via `openJobsTotal`.", "example": 47 }, "byDepartment": { "type": "array", "description": "Open job counts broken down by department. Revealed via `openJobsByDepartment`.", "items": { "$ref": "#/components/schemas/V3OpenJobsByDepartment" } }, "byLocation": { "type": "array", "description": "Open job counts broken down by location. Revealed via `openJobsByLocation`.", "items": { "$ref": "#/components/schemas/V3OpenJobsByLocation" } }, "bySeniority": { "type": "array", "description": "Open job counts broken down by seniority level. Revealed via `openJobsBySeniority`.", "items": { "$ref": "#/components/schemas/V3OpenJobsBySeniority" } } } }, "V3EnrichedCompany": { "type": "object", "properties": { "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "alternativeName": { "type": "string", "example": "lusha" }, "domain": { "type": "string", "example": "www.lusha.com" }, "alternativeDomains": { "type": "array", "items": { "type": "string" }, "example": [ "lusha.com" ] }, "description": { "type": "string", "example": "Lusha is the leader in Sales Streaming." }, "companyType": { "type": "string", "example": "Private Company" }, "yearFounded": { "type": "number", "example": 2016 }, "employeeCount": { "type": "object", "properties": { "exact": { "type": "integer", "example": 364 }, "min": { "type": "integer", "example": 201 }, "max": { "type": "integer", "example": 500 } } }, "industry": { "type": "string", "example": "Technology, Information & Media" }, "subIndustry": { "type": "string", "example": "Software Development" }, "specialities": { "type": "array", "items": { "type": "string" }, "example": [ "data enrichment", "sales intelligence" ] }, "industryTags": { "type": "array", "items": { "type": "string" }, "example": [ "saas", "b2b" ] }, "sicCodes": { "type": "array", "items": { "$ref": "#/components/schemas/V3SicCode" } }, "naicsCodes": { "type": "array", "items": { "$ref": "#/components/schemas/V3NaicsCode" } }, "companyOffering": { "type": "string", "description": "Free field. Short description of what the company sells or does.", "example": "Cloud-based CRM software for small businesses" }, "emailDomain": { "type": "string", "description": "Free field. Primary domain used for company email addresses.", "example": "lusha.com" }, "additionalIndustries": { "type": "array", "description": "Free field. Up to 2 secondary industry classifications beyond the primary `industry`/`subIndustry`.", "maxItems": 2, "items": { "type": "object", "properties": { "industry": { "type": "string", "example": "Financial Services" }, "subIndustry": { "type": "string", "example": "Insurance" } } } }, "estimatedAnnualItSpend": { "type": "object", "description": "Revealed via reveal: [\"estimatedAnnualItSpend\"] in Enrich Companies. Charged 1 credit when non-null.", "nullable": true, "properties": { "value": { "type": "number", "example": 500000 }, "currency": { "type": "string", "example": "USD" }, "valueUsd": { "type": "number", "example": 500000 } } }, "monthlyWebsiteTraffic": { "type": "object", "description": "Revealed via reveal: [\"monthlyWebsiteTraffic\"] in Enrich Companies. Charged 1 credit when non-null.", "nullable": true, "properties": { "visits": { "type": "number", "example": 128450 }, "momChangePercent": { "type": "number", "example": 4.3 }, "month": { "type": "string", "example": "2026-06" } } }, "openJobs": { "$ref": "#/components/schemas/V3OpenJobs" }, "directParent": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3CompanyParent" } ], "description": "The company's immediate parent in its ownership tree. Revealed via reveal: [\"directParent\"] on Enrich Companies and Search & Enrich Companies - it is not returned unless requested. Charged 1 credit when non-null. `null` when the company has no known parent (for example, it is independent or is itself the ultimate parent).", "nullable": true }, "ultimateParent": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3CompanyParent" } ], "description": "The company at the top of its ownership tree. Revealed via reveal: [\"ultimateParent\"] on Enrich Companies and Search & Enrich Companies - it is not returned unless requested. Charged 1 credit when non-null. For a company with a single level of ownership, this matches `directParent`. `null` when the company has no known parent.", "nullable": true }, "location": { "$ref": "#/components/schemas/V3CompanyLocation" }, "additionalLocations": { "type": "array", "items": { "$ref": "#/components/schemas/V3CompanyLocation" } }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/company/lushadata" }, "facebook": { "type": "string", "nullable": true, "description": "Company Facebook page URL. Included automatically when available - no `reveal` entry needed. Omitted from the response when not available (never returned empty). Free field - no credits charged. Available on all plans.\n", "example": "https://www.facebook.com/lusha" }, "x": { "type": "string", "nullable": true, "description": "Company X (formerly Twitter) profile URL. Included automatically when available - no `reveal` entry needed. Omitted from the response when not available (never returned empty). Free field - no credits charged. Available on all plans.\n", "example": "https://x.com/lusha" }, "instagram": { "type": "array", "items": { "type": "string" }, "description": "Company Instagram profile URLs. Included automatically when Lusha holds the data - no `reveal` entry needed, no credit cost. Returned as a list because a company can hold more than one profile on this network; every value Lusha holds is returned. Omitted from the response entirely when no data is available (never returned as `null` or an empty list). Company-level data, contains no personal information, refreshed monthly. Available on all plans.\n", "example": [ "https://www.instagram.com/acmecorp" ] }, "youtube": { "type": "array", "items": { "type": "string" }, "description": "Company YouTube channel URLs. Included automatically when Lusha holds the data - no `reveal` entry needed, no credit cost. Returned as a list because a company can hold more than one channel on this network (multiple YouTube channels are common); every value Lusha holds is returned. Omitted from the response entirely when no data is available (never returned as `null` or an empty list). Company-level data, contains no personal information, refreshed monthly. Available on all plans.\n", "example": [ "https://www.youtube.com/c/acmecorp", "https://www.youtube.com/channel/UCY23V0it8LSbQhB91Esxrbg" ] }, "tiktok": { "type": "array", "items": { "type": "string" }, "description": "Company TikTok profile URLs. Included automatically when Lusha holds the data - no `reveal` entry needed, no credit cost. Returned as a list because a company can hold more than one profile on this network; every value Lusha holds is returned. Omitted from the response entirely when no data is available (never returned as `null` or an empty list). Company-level data, contains no personal information, refreshed monthly. Available on all plans.\n", "example": [ "https://www.tiktok.com/@acmecorp" ] } } }, "linkedinFollowers": { "type": "number", "example": 64339 }, "revenueRange": { "type": "object", "properties": { "min": { "type": "number", "example": 10000000 }, "max": { "type": "number", "example": 50000000 } } }, "funding": { "description": "Funding payload when present" }, "intent": { "description": "Intent payload when present" }, "technologies": { "type": "array", "items": { "type": "string" }, "example": [ "react", "node.js", "aws" ] }, "popularityTier": { "type": "number", "example": 1 }, "logoUrl": { "type": "string", "example": "https://logo.lusha.co/logo.jpg" }, "employeesByDepartment": { "type": "array", "description": "Breakdown of employees by department. Revealed via `reveal: [\"employeesByDepartment\"]` in Enrich Companies.\n", "items": { "type": "object", "properties": { "department": { "type": "string", "description": "Department name", "example": "Engineering & Technical" }, "count": { "type": "integer", "description": "Number of employees in this department", "example": 14 } } }, "example": [ { "department": "Engineering & Technical", "count": 14 }, { "department": "Operations", "count": 40 }, { "department": "Other", "count": 104 } ] }, "employeesByLocation": { "type": "array", "description": "Breakdown of employees by country and state. Revealed via `reveal: [\"employeesByLocation\"]` in Enrich Companies.\n", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "Country name", "example": "United States" }, "state": { "type": "string", "nullable": true, "description": "State or region (null when not available)", "example": "Colorado" }, "count": { "type": "integer", "description": "Number of employees in this location", "example": 54 } } }, "example": [ { "country": "United States", "state": "Colorado", "count": 54 }, { "country": "United States", "state": "Texas", "count": 44 }, { "country": "United States", "state": null, "count": 162 } ] }, "employeesBySeniority": { "type": "array", "description": "Breakdown of employees by seniority level. Revealed via `reveal: [\"employeesBySeniority\"]` in Enrich Companies.\n", "items": { "type": "object", "properties": { "seniority": { "type": "string", "description": "Seniority level", "example": "Manager" }, "count": { "type": "integer", "description": "Number of employees at this seniority level", "example": 39 } } }, "example": [ { "seniority": "Non-Manager", "count": 122 }, { "seniority": "Manager", "count": 39 }, { "seniority": "Vice President", "count": 3 } ] }, "competitors": { "type": "array", "description": "List of competitor companies. Revealed via `reveal: [\"competitors\"]` in Enrich Companies. Use Enrich Companies with the returned IDs to get full firmographic data on each competitor.\n", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Lusha company ID of the competitor", "example": "2497917" }, "name": { "type": "string", "description": "Company name of the competitor", "example": "Clearbit" }, "domain": { "type": "string", "description": "Primary domain of the competitor", "example": "clearbit.com" } } }, "example": [ { "id": "2497917", "name": "Clearbit", "domain": "clearbit.com" }, { "id": "9781263", "name": "Hunter.io", "domain": "hunter.io" }, { "id": "40857684", "name": "MCJ Solutions Inc", "domain": "zoominfo.com" } ] }, "businessModel": { "type": "array", "description": "Company business model classification (e.g. B2B, B2C)", "items": { "type": "string" }, "example": [ "B2B" ] }, "phone": { "type": "string", "description": "Company phone number", "example": "(480) 729-6394" }, "email": { "type": "string", "description": "Company contact email address", "example": "info@cobbmechanical.com" }, "keywords": { "type": "array", "description": "Keywords associated with the company (normalized from specialities and description)", "items": { "type": "string" }, "example": [ "construction", "hvac", "plumbing", "mechanical system" ] }, "specialitiesRefactored": { "type": "array", "description": "Normalized version of the specialities list", "items": { "type": "string" }, "example": [ "construction", "hvac", "industrial piping", "mechanical systems", "plumbing" ] }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3SearchAndEnrichCompanyResult": { "allOf": [ { "$ref": "#/components/schemas/V3EnrichedCompany" }, { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "comp-ref-1" } } } ] }, "ContactLookalikesRequest": { "type": "object", "additionalProperties": false, "required": [ "seeds" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "example": "58adaa77-7a6e-4c9b-8c2d-820a6538e613" }, "seeds": { "allOf": [ { "$ref": "#/components/schemas/ContactIdentifiersBatch" } ], "description": "**Required. Minimum 5, maximum 100 seed contacts in total**, counted across all identifier types combined (`linkedinUrls` + `emails` + `ids` + `contactIds` + `contacts`). Fewer than 5 total seeds is rejected with `400`. Cannot be null." }, "exclude": { "allOf": [ { "$ref": "#/components/schemas/ContactIdentifiersBatch" } ], "description": "Optional. Contacts to always filter out of the results (for example, existing customers). Omit the field entirely if you have nothing to exclude. Subject to the same 100-per-identifier-type cap as `seeds`, but has no minimum." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "example": 25 }, "tableId": { "type": "string", "description": "Optional. If provided, results are also persisted to this table. See the Tables API.", "example": "482910" } } }, "ContactIdentifiersBatch": { "type": "object", "additionalProperties": false, "properties": { "linkedinUrls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "example": [ "https://www.linkedin.com/in/orit-shilvock-6243bb5" ] }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactItem" }, "maxItems": 100 }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100, "example": [ "gal.ashkelon@lusha.com" ] }, "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Lusha contact IDs as strings (preferred)", "example": [ "1234", "4567" ] }, "contactIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 100, "description": "Lusha contact IDs as numbers (legacy; prefer ids)", "example": [ 1234, 4567 ] } }, "minProperties": 1 }, "ContactItem": { "type": "object", "additionalProperties": false, "required": [ "firstName", "lastName" ], "description": "At least one of companyDomain or companyName is required.", "properties": { "firstName": { "type": "string", "example": "Miri" }, "lastName": { "type": "string", "example": "Tamir" }, "companyDomain": { "type": "string", "example": "lusha.com" }, "companyName": { "type": "string", "example": "Lusha" } } }, "ContactLookalikesResponse": { "type": "object", "additionalProperties": false, "required": [ "dedupeSessionId", "results", "meta" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "nullable": true, "example": "58adaa77-7a6e-4c9b-8c2d-820a6538e613" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3LookAlikeContactResult" } }, "meta": { "$ref": "#/components/schemas/ContactLookalikesMeta" }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ContactLookalikesMeta": { "type": "object", "additionalProperties": false, "required": [ "returned", "hasMore" ], "properties": { "returned": { "type": "integer", "example": 25 }, "hasMore": { "type": "boolean", "example": true } } }, "CompanyIdentifiersBatch": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "example": [ "sap.com", "oracle.com" ] }, "linkedinUrls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "example": [ "https://www.linkedin.com/company/sap" ] } }, "minProperties": 1 }, "CompanyLookalikesRequest": { "type": "object", "required": [ "seeds" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "example": "58adaa77-7a6e-4c9b-8c2d-820a6538e613" }, "seeds": { "allOf": [ { "$ref": "#/components/schemas/CompanyIdentifiersBatch" } ], "description": "**Required. Minimum 5, maximum 100 seed companies in total**, counted across all identifier types combined (`domains` + `linkedinUrls`). Fewer than 5 total seeds is rejected with `400`." }, "exclude": { "allOf": [ { "$ref": "#/components/schemas/CompanyIdentifiersBatch" } ], "description": "Optional. Companies to always filter out of the results (for example, existing customers or competitors). Omit the field entirely if you have nothing to exclude. Subject to the same 100-per-identifier-type cap as `seeds`, but has no minimum." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "example": 25 }, "tableId": { "type": "string", "description": "Optional. If provided, results are also persisted to this table. See the Tables API.", "example": "583021" } } }, "CompanyLookalikesResponse": { "type": "object", "required": [ "dedupeSessionId", "results", "meta" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "example": "58adaa77-7a6e-4c9b-8c2d-820a6538e613" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3LookAlikeCompanyResult" } }, "meta": { "$ref": "#/components/schemas/CompanyLookalikesMeta" }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "CompanyLookalikesMeta": { "type": "object", "required": [ "returned", "hasMore" ], "properties": { "returned": { "type": "integer", "example": 1 }, "hasMore": { "type": "boolean", "example": true } } }, "V3LookAlikeCompanyResult": { "type": "object", "properties": { "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Marriott International" }, "domain": { "type": "string", "example": "marriott.com" }, "employeeCount": { "type": "object", "properties": { "exact": { "type": "integer", "example": 255334 } } }, "industry": { "type": "string", "example": "Hospitality" }, "location": { "type": "object", "properties": { "country": { "type": "string", "example": "United States" }, "state": { "type": "string", "example": "Maryland" }, "city": { "type": "string", "example": "Bethesda" } } }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/company/marriott-international" } } } } }, "V3LookAlikeContactResult": { "type": "object", "properties": { "id": { "type": "string", "example": "4389064624" }, "firstName": { "type": "string", "example": "Yehuda" }, "lastName": { "type": "string", "example": "Rapp" }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/yehuda-rapp-53909b99" } } }, "company": { "type": "object", "properties": { "id": { "type": "string", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "www.lusha.com" } } }, "jobTitle": { "type": "object", "properties": { "title": { "type": "string", "example": "Senior Solutions Engineer" }, "departments": { "type": "array", "items": { "type": "string" }, "example": [ "Engineering & Technical" ] }, "seniority": { "type": "string", "example": "Senior" } } }, "location": { "type": "object", "properties": { "country": { "type": "string", "example": "Israel" }, "state": { "type": "string", "example": "Tel Aviv District" }, "city": { "type": "string", "example": "Tel Aviv" } } } } }, "V3BuyingGroupCompanyItem": { "type": "object", "description": "Identifies one target company. Provide exactly one of domain or id.", "properties": { "clientReferenceId": { "type": "string", "description": "Optional caller-supplied token, echoed back on the matching result.", "example": "comp-ref-1" }, "domain": { "type": "string", "example": "acme.com" }, "id": { "type": "string", "description": "Lusha company ID.", "example": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" } } }, "V3BuyingGroupRequest": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/V3BuyingGroupCompanyItem" }, "minItems": 1, "maxItems": 25 }, "personas": { "type": "array", "description": "Filter results to specific persona roles. Omit to return all three.", "items": { "type": "string", "enum": [ "decision_maker", "potential_champion", "end_user" ] }, "example": [ "decision_maker", "potential_champion" ] }, "contactsLimit": { "type": "integer", "description": "Maximum number of contacts returned per company.", "default": 60, "minimum": 1, "example": 20 }, "pagination": { "type": "object", "description": "Optional. If omitted, defaults to page 0, size 100.", "properties": { "page": { "type": "integer", "minimum": 0, "default": 0, "example": 0 }, "size": { "type": "integer", "minimum": 10, "maximum": 100, "default": 100, "example": 100 } } } } }, "V3BuyingGroupContact": { "type": "object", "properties": { "id": { "type": "string", "example": "v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ" }, "firstName": { "type": "string", "example": "Mohammed" }, "lastName": { "type": "string", "example": "Alam" }, "jobTitle": { "type": "object", "properties": { "title": { "type": "string", "example": "RF/Analog IC Design Engineer" }, "departments": { "type": "array", "items": { "type": "string" }, "example": [ "Engineering & Technical" ] }, "seniority": { "type": "string", "example": "Non-Manager" } } }, "company": { "type": "object", "properties": { "id": { "type": "string", "example": "v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP" }, "name": { "type": "string", "example": "Intel" }, "domain": { "type": "string", "example": "www.intel.com" } } }, "location": { "type": "object", "properties": { "country": { "type": "string", "example": "United States" }, "state": { "type": "string", "example": "Arizona" }, "city": { "type": "string", "example": "Chandler" } } }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/mohammed-alam-83759111" } } }, "has": { "type": "array", "items": { "type": "string" }, "example": [ "firstName", "lastName", "jobTitle", "company", "location", "socialLinks", "phones", "previousEmployment", "jobStartDate" ] }, "canReveal": { "type": "array", "items": { "$ref": "#/components/schemas/V3CanRevealItem" } }, "roles": { "type": "array", "description": "Persona role(s) the model assigned to this contact.", "items": { "type": "string", "enum": [ "decision_maker", "potential_champion", "end_user" ] }, "example": [ "potential_champion" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score for the assigned role(s).", "example": 0.8872673511505127 }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3BuyingGroupCompanyResult": { "type": "object", "properties": { "clientReferenceId": { "type": "string", "example": "comp-ref-1" }, "companyId": { "type": "string", "example": "v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BuyingGroupContact" } }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3BuyingGroupResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "example": "951d46da-24f9-4608-84bf-5e70a10bf851" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3BuyingGroupCompanyResult" } }, "pagination": { "$ref": "#/components/schemas/V3PaginationResponse" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ProspectingContactFilters": { "type": "object", "properties": { "contacts": { "type": "object", "properties": { "include": { "$ref": "#/components/schemas/V3ContactFilterCriteria" }, "exclude": { "$ref": "#/components/schemas/V3ContactFilterCriteria" } } }, "companies": { "type": "object", "properties": { "include": { "$ref": "#/components/schemas/V3CompanyFilterCriteria" }, "exclude": { "$ref": "#/components/schemas/V3CompanyFilterCriteria" } } } } }, "V3ContactFilterCriteria": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" } }, "jobTitles": { "type": "array", "items": { "type": "string" }, "example": [ "VP Sales", "Director of Sales" ] }, "jobTitlesExactMatch": { "type": "array", "items": { "type": "string" } }, "normalizedJobTitles": { "type": "array", "items": { "type": "string" } }, "searchText": { "type": "string", "maxLength": 200 }, "countries": { "type": "array", "items": { "type": "string" }, "example": [ "US", "CA" ] }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/V3Location" } }, "seniorityIds": { "type": "array", "items": { "type": "integer" }, "example": [ 4, 5 ] }, "departments": { "type": "array", "items": { "type": "string" }, "example": [ "Sales", "Engineering" ] }, "linkedinUrls": { "type": "array", "items": { "type": "string" } }, "existingDataPoints": { "type": "array", "items": { "type": "string" }, "example": [ "work_email", "work_phone" ] }, "signals": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] } }, "startDate": { "type": "string", "format": "date" } } }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Personal data - no catalog." }, "previousEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Personal data - no catalog." }, "previousJobTitle": { "type": "array", "items": { "type": "string" } }, "skills": { "type": "array", "items": { "type": "string" }, "example": [ "Python" ] }, "certifications": { "type": "array", "items": { "type": "string" } }, "awards": { "type": "array", "items": { "type": "string" } }, "ids": { "type": "array", "items": { "type": "string" }, "description": "Encrypted contact id from a prior search's `results[].id`." }, "existingDataPointsCondition": { "type": "string", "enum": [ "or", "and" ], "description": "Pairs with `existingDataPoints`." }, "jobChangedAfterDate": { "type": "string", "format": "date", "description": "Refinement-only - must be paired with a base filter (e.g. `jobTitles`)." }, "jobChangedLastViewDate": { "type": "string", "format": "date", "description": "Refinement-only - must be paired with a base filter." }, "education": { "type": "object", "description": "Refinement-only - must be paired with a base filter.", "properties": { "degrees": { "type": "array", "items": { "type": "string" } }, "fieldsOfStudy": { "type": "array", "items": { "type": "string" } }, "schools": { "type": "array", "items": { "type": "string" } }, "startYearGte": { "type": "integer" }, "graduationYearLte": { "type": "integer" } } }, "score": { "type": "object", "description": "Refinement-only - must be paired with a base filter. Raw 0–100 contact score. Distinct from the `confidence` band (\"A+\"/\"A\") returned on enriched contacts, which is derived from this score (e.g. `A+` when score > 75).\n", "properties": { "minScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxScore": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "geographicDetails": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "zipcode": { "type": "string" }, "distance": { "type": "integer", "description": "Radius in miles." } } } } } }, "V3CompanyFilterCriteria": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" }, "example": [ "lusha.com" ] }, "ids": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/V3Location" } }, "sizes": { "type": "array", "items": { "$ref": "#/components/schemas/V3Range" }, "example": [ { "min": 50, "max": 500 } ] }, "revenues": { "type": "array", "items": { "$ref": "#/components/schemas/V3Range" } }, "technologies": { "type": "array", "items": { "type": "string" }, "example": [ "Salesforce", "HubSpot" ] }, "technologiesCondition": { "type": "string", "enum": [ "or", "and" ], "example": "or" }, "industriesLabels": { "type": "array", "items": { "type": "string" }, "example": [ "Software", "SaaS" ] }, "mainIndustriesIds": { "type": "array", "items": { "type": "integer" } }, "subIndustriesIds": { "type": "array", "items": { "type": "integer" } }, "intentTopics": { "type": "array", "items": { "type": "string" }, "example": [ "Cloud Migration" ] }, "intentTopicsCondition": { "type": "string", "enum": [ "or", "and" ] }, "intentMinScore": { "type": "integer", "minimum": 1, "maximum": 100 }, "intentMaxScore": { "type": "integer", "minimum": 1, "maximum": 100 }, "intentTopicsOperator": { "type": "string", "enum": [ "or", "and", "any", "all" ], "description": "Recommended over `intentTopicsCondition`. `any`/`all` are aliases for `or`/`and`. `intentTopicsCondition` is not deprecated and remains accepted.\n" }, "topicCountThreshold": { "type": "array", "items": { "$ref": "#/components/schemas/V3Range" } }, "sicCodes": { "type": "array", "items": { "type": "string" } }, "naicsCodes": { "type": "array", "items": { "type": "string" } }, "funding": { "type": "object", "description": "All funding sub-filters live under this single object. Every field is optional; combine any subset.\n", "properties": { "isIpo": { "type": "boolean" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "coverage": { "type": "string", "enum": [ "last_funding", "any_round", "total_funds", "last_round" ] }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "date": { "type": "object", "properties": { "coverage": { "type": "string", "enum": [ "last_funding", "any_round", "total_funds", "last_round" ] }, "date": { "type": "string", "format": "date" } } }, "rounds": { "type": "array", "items": { "type": "object", "properties": { "coverage": { "type": "string", "enum": [ "last_funding", "any_round", "total_funds", "last_round" ] }, "round": { "type": "string", "enum": [ "pre_seed", "seed", "series_a", "series_b", "series_c", "series_d", "series_e", "series_f", "series_g", "series_h", "other" ] } } } }, "names": { "type": "array", "items": { "type": "object", "properties": { "coverage": { "type": "string", "enum": [ "last_funding", "any_round", "total_funds", "last_round" ] }, "name": { "type": "string", "enum": [ "angel", "venture", "private_equity", "crowdfunding", "grant", "debt_financing", "other" ] } } } }, "investors": { "type": "array", "items": { "type": "string" }, "description": "Free text. Accepted but not currently applied downstream." }, "types": { "type": "array", "items": { "type": "string" }, "description": "Legacy free text. Accepted but not currently applied downstream." } } }, "foundedYear": { "type": "array", "description": "Filter by year the company was founded. Supports `min` (greater than or equal) and `max` (less than or equal) range operators.", "items": { "type": "object", "properties": { "min": { "type": "integer", "example": 2000 }, "max": { "type": "integer", "example": 2020 } } } }, "businessModel": { "type": "array", "description": "Filter by business model. Accepted values: B2B, B2C, B2G.", "items": { "type": "string", "enum": [ "B2B", "B2C", "B2G" ] }, "example": [ "B2B" ] }, "companyType": { "type": "array", "description": "Filter by company type. Accepted values: Government, Private Company, Public Company, Educational, Non Profit, Self Employed.", "items": { "type": "string", "enum": [ "Government", "Private Company", "Public Company", "Educational", "Non Profit", "Self Employed" ] }, "example": [ "Public Company" ] }, "linkedinUrls": { "type": "array", "description": "Filter by company LinkedIn URLs.", "items": { "type": "string" }, "example": [ "https://www.linkedin.com/company/google" ] }, "keywords": { "type": "array", "description": "Filter by keywords associated with the company.", "items": { "type": "string" }, "example": [ "fintech" ] }, "specialities": { "type": "array", "items": { "type": "string" } }, "exactSpecialities": { "type": "array", "items": { "type": "string" } }, "exactKeywords": { "type": "array", "items": { "type": "string" } }, "keywordsSearchFields": { "type": "array", "items": { "type": "string" } }, "previousCompanyDomains": { "type": "array", "items": { "type": "string" } }, "previousCompanyNames": { "type": "array", "items": { "type": "string" } }, "geographicDetails": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "zipcode": { "type": "string" }, "distance": { "type": "integer", "description": "Radius in miles." } } } }, "locationsZipcodes": { "type": "array", "items": { "type": "object", "properties": { "countryIso2": { "type": "string" }, "zipcode": { "type": "string" } } } }, "headquarterZipcodes": { "type": "array", "items": { "type": "object", "properties": { "countryIso2": { "type": "string" }, "zipcode": { "type": "string" } } } } } }, "V3CompanyProspectingFilters": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "ids": { "type": "array", "items": { "type": "string" } }, "searchText": { "type": "string", "maxLength": 200 }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/V3Location" } }, "sizes": { "type": "array", "items": { "$ref": "#/components/schemas/V3Range" } }, "revenues": { "type": "array", "items": { "$ref": "#/components/schemas/V3Range" } }, "technologies": { "type": "array", "items": { "type": "string" } }, "technologiesCondition": { "type": "string", "enum": [ "or", "and" ] }, "mainIndustriesIds": { "type": "array", "items": { "type": "integer" } }, "subIndustriesIds": { "type": "array", "items": { "type": "integer" } }, "intentTopics": { "type": "array", "items": { "type": "string" } }, "intentTopicsCondition": { "type": "string", "enum": [ "or", "and" ] }, "intentMinScore": { "type": "integer", "minimum": 1, "maximum": 100 }, "intentMaxScore": { "type": "integer", "minimum": 1, "maximum": 100 }, "intentTopicsOperator": { "type": "string", "enum": [ "or", "and", "any", "all" ], "description": "Recommended over `intentTopicsCondition`. `any`/`all` are aliases for `or`/`and`. `intentTopicsCondition` is not deprecated and remains accepted.\n" }, "topicCountThreshold": { "type": "array", "items": { "$ref": "#/components/schemas/V3Range" } }, "sicCodes": { "type": "array", "items": { "type": "string" } }, "naicsCodes": { "type": "array", "items": { "type": "string" } }, "signals": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" }, "example": [ "headcountIncrease3m", "surgeInHiring", "linkedinActivityIntent" ] }, "startDate": { "type": "string", "format": "date" }, "filterByLocation": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "state": { "type": "string" }, "startDate": { "type": "string", "format": "date" } } } }, "filterByDepartment": { "type": "array", "items": { "type": "object", "required": [ "department" ], "properties": { "department": { "type": "string", "example": "Engineering & Technical" }, "startDate": { "type": "string", "format": "date" } } } }, "filterByIntentCategory": { "type": "array", "items": { "type": "string" }, "description": "Refines linkedinActivityIntent results by Bombora intent category. Applied only when linkedinActivityIntent is present in `types` (or selected via allSignals). Omit to match all categories. See GET /v3/companies/signals/filters/intentCategories for the full list of valid values.\n", "example": [ "Technology" ] } } }, "foundedYear": { "type": "array", "description": "Filter by year the company was founded. Supports `min` (greater than or equal) and `max` (less than or equal) range operators.", "items": { "type": "object", "properties": { "min": { "type": "integer", "example": 1990 }, "max": { "type": "integer", "example": 2020 } } } }, "businessModel": { "type": "array", "description": "Filter by business model. Accepted values: B2B, B2C, B2G.", "items": { "type": "string", "enum": [ "B2B", "B2C", "B2G" ] }, "example": [ "B2B", "B2G" ] }, "companyType": { "type": "array", "description": "Filter by company type. Accepted values: Government, Private Company, Public Company, Educational, Non Profit, Self Employed.", "items": { "type": "string", "enum": [ "Government", "Private Company", "Public Company", "Educational", "Non Profit", "Self Employed" ] }, "example": [ "Public Company", "Private Company" ] }, "linkedinUrls": { "type": "array", "description": "Filter by company LinkedIn URLs.", "items": { "type": "string" }, "example": [ "https://www.linkedin.com/company/microsoft" ] }, "keywords": { "type": "array", "description": "Filter by keywords associated with the company.", "items": { "type": "string" }, "example": [ "cloud", "artificial intelligence" ] }, "specialities": { "type": "array", "items": { "type": "string" } }, "exactSpecialities": { "type": "array", "items": { "type": "string" } }, "exactKeywords": { "type": "array", "items": { "type": "string" } }, "keywordsSearchFields": { "type": "array", "items": { "type": "string" } }, "previousCompanyDomains": { "type": "array", "items": { "type": "string" } }, "previousCompanyNames": { "type": "array", "items": { "type": "string" } }, "geographicDetails": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "zipcode": { "type": "string" }, "distance": { "type": "integer", "description": "Radius in miles." } } } }, "locationsZipcodes": { "type": "array", "items": { "type": "object", "properties": { "countryIso2": { "type": "string" }, "zipcode": { "type": "string" } } } }, "headquarterZipcodes": { "type": "array", "items": { "type": "object", "properties": { "countryIso2": { "type": "string" }, "zipcode": { "type": "string" } } } } } }, "V3ContactSignalsRequest": { "type": "object", "required": [ "ids", "signalTypes" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "example": [ "4389064624", "4389064654" ] }, "signalTypes": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] }, "example": [ "allSignals" ] }, "startDate": { "type": "string", "format": "date", "example": "2025-01-01" }, "maxResultsPerSignal": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "tableId": { "type": "string", "description": "Optional. If provided, these contacts are also added to this table (if not already present) and the Signals column is populated. See the Tables API.", "example": "482910" } } }, "V3ContactSignalsResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "4389064624" }, "companyChange": { "type": "array", "items": { "type": "object" } }, "promotion": { "type": "array", "items": { "type": "object" } } } } }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3CompanySignalsRequest": { "type": "object", "required": [ "ids", "signalTypes" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "example": [ "16303253" ] }, "signalTypes": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "linkedinActivityIntent", "websiteTrafficDecrease", "websiteTrafficIncrease", "itSpendIncrease", "itSpendDecrease", "surgeInHiring", "headcountIncrease1m", "headcountIncrease3m", "headcountIncrease6m", "headcountIncrease12m", "headcountDecrease1m", "headcountDecrease3m", "headcountDecrease6m", "headcountDecrease12m", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": [ "allSignals" ] }, "startDate": { "type": "string", "format": "date", "description": "For linkedinActivityIntent, results are limited to a trailing 90-day window regardless of the value passed (legal requirement). Other signal types are unaffected.\n", "example": "2025-01-01" }, "maxResultsPerSignal": { "type": "integer", "minimum": 1, "maximum": 100, "description": "For linkedinActivityIntent, results are capped at 50 per company regardless of the value passed. Other signal types use the requested value as-is (1-100).\n", "example": 10 }, "tableId": { "type": "string", "description": "Optional. If provided, these companies are also added to this table (if not already present) and the Signals column is populated. See the Tables API.", "example": "583021" }, "filters": { "type": "object", "properties": { "include": { "type": "object", "properties": { "intentCategories": { "type": "array", "items": { "type": "string" }, "description": "Refines linkedinActivityIntent results by Bombora intent category. Only applies when linkedinActivityIntent is requested (via signalTypes or allSignals). See GET /v3/companies/signals/filters/intentCategories for valid values.\n", "example": [ "Technology", "Business" ] } } } } } } }, "LinkedinActivityIntentTopic": { "type": "object", "properties": { "topic": { "type": "string", "example": "Cloud Security" }, "category": { "type": "string", "example": "Technology" } } }, "LinkedinActivityIntentPerson": { "type": "object", "description": "A person referenced in a LinkedIn activity intent post (author or mention).", "properties": { "id": { "type": "string", "nullable": true, "description": "Lusha contact ID, or null if the person couldn't be resolved to a Lusha record.", "example": "4389064624" }, "fullName": { "type": "string", "example": "Daniel Turgeman" }, "linkedinUrl": { "type": "string", "example": "https://www.linkedin.com/in/daniel-turgeman-49676b161" } } }, "LinkedinActivityIntentCompanyMention": { "type": "object", "description": "A company referenced in a LinkedIn activity intent post.", "properties": { "id": { "type": "string", "nullable": true, "description": "Lusha company ID, or null if the company couldn't be resolved to a Lusha record.", "example": "16303253" }, "name": { "type": "string", "example": "Lusha" }, "linkedinUrl": { "type": "string", "example": "https://www.linkedin.com/company/lushadata" } } }, "LinkedinActivityIntentItem": { "type": "object", "properties": { "companyId": { "type": "number", "description": "Lusha company ID this activity belongs to.", "example": 16303253 }, "activityPublicationDate": { "type": "string", "format": "date", "description": "Date the post was published.", "example": "2026-05-12" }, "signalCategory": { "type": "string", "description": "Post classification.", "example": "Technology or Stack Discussion" }, "intentTopics": { "type": "array", "description": "Detected Bombora topics and their category.", "items": { "$ref": "#/components/schemas/LinkedinActivityIntentTopic" } }, "author": { "$ref": "#/components/schemas/LinkedinActivityIntentPerson" }, "contactsMentioned": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinActivityIntentPerson" } }, "companiesMentioned": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinActivityIntentCompanyMention" } }, "activityUrl": { "type": "string", "description": "URL of the source post.", "example": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890" }, "activitySummary": { "type": "string", "nullable": true, "description": "AI-generated summary. Never contains the raw post text.", "example": "Discusses adopting a new cloud security stack ahead of Q3 rollout." }, "activityLikes": { "type": "integer", "default": 0, "example": 42 }, "activityComments": { "type": "integer", "default": 0, "example": 5 }, "activityShares": { "type": "integer", "default": 0, "example": 3 }, "activityType": { "type": "string", "example": "post" } } }, "V3CompanySignalsResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "16303253" }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" }, "linkedinActivityIntent": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinActivityIntentItem" } } }, "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ContactSignalTypesResponse": { "type": "object", "properties": { "signalTypes": { "type": "array", "items": { "type": "string" }, "example": [ "allSignals", "promotion", "companyChange" ] } } }, "CompanySignalTypesResponse": { "type": "object", "properties": { "signalTypes": { "type": "array", "items": { "type": "string" } } } }, "V3SignalScoreCompanyItem": { "type": "object", "description": "Must contain exactly one of id, domain, name, or email.", "properties": { "clientReferenceId": { "type": "string", "maxLength": 256, "description": "Caller-supplied token echoed back on the matching result.", "example": "ref-1" }, "id": { "type": "string", "description": "Encrypted Lusha company ID (vN.…). Legacy numeric IDs accepted during the transition window.", "example": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" }, "domain": { "type": "string", "example": "www.microsoft.com" }, "name": { "type": "string", "example": "Apple" }, "email": { "type": "string", "format": "email", "description": "Must be a valid email address; only the domain part is used for resolution. A malformed email is rejected with 400.", "example": "jane@acme.com" } } }, "V3SignalScoreCompaniesRequest": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/V3SignalScoreCompanyItem" }, "minItems": 1, "maxItems": 100 } } }, "V3SignalScoreCompanyResult": { "type": "object", "description": "A scored entry, or an error entry with NOT_FOUND / NO_SCORE instead of the score fields.", "properties": { "clientReferenceId": { "type": "string", "example": "ref-1" }, "id": { "type": "string", "description": "Encrypted Lusha company ID for scored entries. On NOT_FOUND, echoes the supplied domain/name (or the derived domain, for an email request).", "example": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" }, "name": { "type": "string", "example": "Acme Corp" }, "domain": { "type": "string", "example": "www.acmecorp.io" }, "signalScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Aggregate signal score - the fraction of the company's active signals. Absent on error entries.", "example": 0.42 }, "signalTypes": { "type": "array", "description": "Signal types currently active for this company (canonical camelCase). Absent on error entries.", "items": { "type": "string" }, "example": [ "hiringSignalIncrease", "websiteVisit" ] }, "noActiveSignals": { "type": "boolean", "description": "True when the company resolved and scored but has no active signals (signalScore is 0). Absent on error entries.", "example": false }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3SignalScoreCompaniesResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "example": "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3SignalScoreCompanyResult" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3SignalScoreContactItem": { "type": "object", "description": "Must contain id, linkedinUrl, email, or firstName + lastName + (companyName | companyDomain).\n", "properties": { "clientReferenceId": { "type": "string", "maxLength": 256, "example": "ref-1" }, "id": { "type": "string", "description": "Encrypted Lusha contact ID (vN.…).", "example": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" }, "linkedinUrl": { "type": "string", "example": "https://linkedin.com/in/johndoe" }, "email": { "type": "string", "format": "email", "example": "jane.doe@acme.com" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "companyName": { "type": "string", "example": "Acme Corp" }, "companyDomain": { "type": "string", "example": "acme.com" } } }, "V3SignalScoreContactsRequest": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/V3SignalScoreContactItem" }, "minItems": 1, "maxItems": 100 } } }, "V3SignalScoreContactCompanyRef": { "type": "object", "description": "Company the contact was scored at.", "properties": { "id": { "type": "string", "example": "v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01" }, "name": { "type": "string", "example": "Acme Corp" }, "domain": { "type": "string", "example": "acme.com" } } }, "V3SignalScoreContactResult": { "type": "object", "description": "A scored entry, or an error entry with NOT_FOUND / NO_SCORE instead of the score fields.", "properties": { "clientReferenceId": { "type": "string", "example": "ref-1" }, "id": { "type": "string", "description": "Encrypted Lusha contact ID for scored entries. On NOT_FOUND, echoes the supplied id, if one was given.", "example": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345" }, "fullName": { "type": "string", "example": "Jane Doe" }, "company": { "$ref": "#/components/schemas/V3SignalScoreContactCompanyRef" }, "signalScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Aggregate signal score. Absent on error entries.", "example": 0.3 }, "signalTypes": { "type": "array", "description": "Signal types currently active for this contact (canonical camelCase). Absent on error entries.", "items": { "type": "string" }, "example": [ "promotion" ] }, "noActiveSignals": { "type": "boolean", "description": "True when the contact resolved and scored but has no active signals (signalScore is 0). Absent on error entries.", "example": false }, "error": { "$ref": "#/components/schemas/V3ItemError" } } }, "V3SignalScoreContactsResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "example": "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3SignalScoreContactResult" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "FilterTypesDiscoveryResponse": { "type": "object", "properties": { "availableFilters": { "type": "array", "items": { "type": "object", "properties": { "filterType": { "type": "string" }, "requiresQuery": { "type": "boolean" } } } } } }, "FilterValuesResponse": { "type": "object", "properties": { "values": { "description": "Filter values (shape depends on filter type)", "nullable": true } } }, "V3ContactsSearchRequest": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/V3ContactSearchItem" }, "minItems": 1, "maxItems": 100 }, "options": { "$ref": "#/components/schemas/V3SearchOptions" }, "signals": { "$ref": "#/components/schemas/V3ContactSignalsDto" } } }, "V3ContactsSearchResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "example": "3c7f6d96-4a72-40cd-96c1-2efcfabeb727" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3ContactPreview" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ContactsEnrichRequest": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "example": [ "4389064654", "4389064624" ] }, "reveal": { "type": "array", "items": { "type": "string", "enum": [ "emails", "phones" ] }, "example": [ "emails", "phones" ] }, "waterfallEnabled": { "type": "boolean", "default": true, "description": "Whether this call is allowed to fall through to your enabled\nthird-party providers when Lusha's own data has no match, for the fields\nrequested via `reveal`. Defaults to `true` whenever Data Waterfall is\nenabled on your account (Account > Waterfall) - pass `false` to opt this\nspecific call out. Has no effect if Data Waterfall or no providers are\nenabled on your account. Provider order isn't configurable - Lusha manages\nthat internally.\n", "example": false }, "tableId": { "type": "string", "description": "Optional. If provided, these contacts are also added to this table (if not already present) and the revealed fields' columns are populated. See the Tables API.", "example": "482910" } } }, "V3ContactsEnrichResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3EnrichedContact" } }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ContactsSearchAndEnrichRequest": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/V3ContactSearchItem" }, "minItems": 1, "maxItems": 100 }, "reveal": { "type": "array", "items": { "type": "string", "enum": [ "emails", "phones" ] }, "example": [ "emails", "phones" ] }, "options": { "$ref": "#/components/schemas/V3SearchOptions" } } }, "V3ContactsSearchAndEnrichResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3SearchAndEnrichContactResult" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3CompaniesSearchRequest": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/V3CompanySearchItem" }, "minItems": 1, "maxItems": 100 }, "options": { "$ref": "#/components/schemas/V3SearchOptions" }, "signals": { "$ref": "#/components/schemas/V3CompanySignalsDto" } } }, "V3CompaniesSearchResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3CompanyPreview" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3CompaniesEnrichRequest": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "Company IDs from search results (strings)", "example": [ "16303253", "12790225" ] }, "reveal": { "type": "array", "items": { "type": "string", "enum": [ "employeesByDepartment", "employeesByLocation", "employeesBySeniority", "competitors", "intent", "estimatedAnnualItSpend", "monthlyWebsiteTraffic", "openJobsTotal", "openJobsByDepartment", "openJobsByLocation", "openJobsBySeniority", "directParent", "ultimateParent" ] }, "description": "Additional data fields to reveal. Each field is charged separately per result.\n- `employeesByDepartment` - breakdown of employees by department\n- `employeesByLocation` - breakdown of employees by country/state\n- `employeesBySeniority` - breakdown of employees by seniority level\n- `competitors` - list of competitor company IDs\n- `intent` - buyer intent topics\n- `estimatedAnnualItSpend` - estimated annual IT spend.\n- `monthlyWebsiteTraffic` - monthly website traffic and month-over-month change.\n- `openJobsTotal` - reveals the total open job count. In the response, this appears as the `total` field inside the `openJobs` object.\n- `openJobsByDepartment` - reveals open job counts broken down by department. In the response, this appears as the `byDepartment` field inside the `openJobs` object.\n- `openJobsByLocation` - reveals open job counts broken down by location. In the response, this appears as the `byLocation` field inside the `openJobs` object.\n- `openJobsBySeniority` - reveals open job counts broken down by seniority level. In the response, this appears as the `bySeniority` field inside the `openJobs` object.\n- `directParent` - the company's immediate parent in its ownership tree.\n- `ultimateParent` - the company at the top of its ownership tree.\n", "example": [ "employeesByDepartment", "employeesByLocation", "employeesBySeniority", "competitors", "intent", "estimatedAnnualItSpend", "monthlyWebsiteTraffic", "openJobsTotal", "openJobsByDepartment", "openJobsByLocation", "openJobsBySeniority", "directParent", "ultimateParent" ] }, "tableId": { "type": "string", "description": "Optional. If provided, these companies are also added to this table (if not already present) and the revealed fields' columns are populated. See the Tables API.", "example": "583021" } } }, "V3CompaniesEnrichResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3EnrichedCompany" } }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3CompaniesSearchAndEnrichRequest": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/V3CompanySearchItem" }, "minItems": 1, "maxItems": 100 }, "reveal": { "type": "array", "items": { "type": "string", "enum": [ "employeesByDepartment", "employeesByLocation", "employeesBySeniority", "competitors", "intent", "estimatedAnnualItSpend", "monthlyWebsiteTraffic", "openJobsTotal", "openJobsByDepartment", "openJobsByLocation", "openJobsBySeniority", "directParent", "ultimateParent" ] }, "description": "Additional data fields to reveal, using the same tokens as Enrich Companies.\nEach field is charged separately per result. Premium fields are returned only\nwhen named here - omitting `reveal` returns base firmographics alone.\nSee [Enrich Companies](#operation/enrichCompanies) for what each token unlocks.\n", "example": [ "directParent", "ultimateParent" ] }, "options": { "$ref": "#/components/schemas/V3SearchOptions" } } }, "V3CompaniesSearchAndEnrichResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3SearchAndEnrichCompanyResult" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ProspectingContactsRequest": { "type": "object", "required": [ "pagination", "filters" ], "properties": { "pagination": { "$ref": "#/components/schemas/V3PaginationRequest" }, "filters": { "$ref": "#/components/schemas/V3ProspectingContactFilters" }, "tableId": { "type": "string", "description": "Optional. If provided, results are also persisted to this table. See the Tables API.", "example": "482910" }, "options": { "type": "object", "properties": { "includePartialProfiles": { "type": "boolean", "default": true }, "excludeDnc": { "type": "boolean" }, "maxContactsPerCompany": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Caps how many contacts are returned per company - not the page size. `pagination.size` still controls the page size. Accepts 1–20; omit for uncapped results.\n", "example": 2 } } } } }, "V3ProspectingContactsResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3ContactPreview" } }, "pagination": { "$ref": "#/components/schemas/V3ProspectingContactsPagination" }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ProspectingCompaniesRequest": { "type": "object", "required": [ "pagination", "filters" ], "properties": { "pagination": { "$ref": "#/components/schemas/V3PaginationRequest" }, "filters": { "type": "object", "required": [ "companies" ], "description": "`filters.contacts` cannot be combined with company `searchText`, `signals`, `intent`, or `technologies` on the same request - doing so returns `400` (contact filters are never silently ignored).\n", "properties": { "companies": { "type": "object", "required": [ "include" ], "properties": { "include": { "$ref": "#/components/schemas/V3CompanyProspectingFilters" }, "exclude": { "$ref": "#/components/schemas/V3CompanyProspectingFilters" } } }, "contacts": { "type": "object", "properties": { "include": { "$ref": "#/components/schemas/V3ContactsOnCompanySearchFilters" }, "exclude": { "$ref": "#/components/schemas/V3ContactsOnCompanySearchFilters" } } } } }, "tableId": { "type": "string", "description": "Optional. If provided, results are also persisted to this table. See the Tables API.", "example": "583021" }, "options": { "type": "object", "properties": { "includePartialProfiles": { "type": "boolean", "default": false } } } } }, "V3ProspectingCompaniesResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/V3CompanyPreview" } }, "pagination": { "$ref": "#/components/schemas/V3PaginationResponse" }, "tableWrite": { "$ref": "#/components/schemas/TableWrite" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "V3ContactsOnCompanySearchFilters": { "type": "object", "description": "Restricted contact-attribute filters usable within a company prospecting request.", "properties": { "jobTitles": { "type": "array", "items": { "type": "string" } }, "departments": { "type": "array", "items": { "type": "string" } }, "seniorityIds": { "type": "array", "items": { "type": "integer" } }, "skills": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/V3Location" } }, "existingDataPoints": { "type": "array", "items": { "type": "string" } } } }, "CreditsUsage": { "type": "object", "properties": { "total": { "type": "number", "example": 10000 }, "used": { "type": "number", "example": 1500 }, "remaining": { "type": "number", "example": 8500 } } }, "RateLimitTier": { "type": "object", "properties": { "limit": { "type": "number", "example": 5000 }, "used": { "type": "number", "example": 120 }, "remaining": { "type": "number", "example": 4880 }, "resetsAt": { "type": "string", "format": "date-time", "example": "2026-03-31T00:00:00.000Z" } } }, "RateLimits": { "type": "object", "properties": { "daily": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RateLimitTier" } ] }, "hourly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RateLimitTier" } ] }, "minute": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RateLimitTier" } ] } } }, "PlanInfo": { "type": "object", "properties": { "category": { "type": "string", "example": "professional" }, "renewalType": { "type": "string", "example": "annual" }, "startDate": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Renewal/end date. Omitted (null) for free accounts, since they have no renewal cycle.", "example": "2027-01-01T00:00:00.000Z" } } }, "PricingEntry": { "type": "object", "properties": { "credits": { "type": "number", "example": 1 }, "perQuantity": { "type": "number", "example": 25 } } }, "AccountUsageResponse": { "type": "object", "properties": { "credits": { "$ref": "#/components/schemas/CreditsUsage" }, "rateLimits": { "$ref": "#/components/schemas/RateLimits" }, "plan": { "$ref": "#/components/schemas/PlanInfo" }, "pricing": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PricingEntry" } } } }, "CreateSubscriptionRequest": { "type": "object", "required": [ "defaults", "subscriptions" ], "properties": { "defaults": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Webhook URL (HTTPS required in production)", "example": "https://example.com/webhooks/lusha" }, "entityType": { "type": "string", "enum": [ "contact", "company" ], "description": "Default entity type for all subscriptions", "example": "contact" }, "signalTypes": { "type": "array", "items": { "type": "string" }, "description": "Default signal types for all subscriptions", "example": [ "promotion" ] } } }, "name": { "type": "string", "maxLength": 100, "description": "Default subscription name prefix", "example": "Contact Webhook" }, "subscriptions": { "type": "array", "minItems": 1, "maxItems": 25, "description": "Array of subscriptions to create (max 25)", "items": { "type": "object", "required": [ "entityId" ], "properties": { "entityId": { "type": "string", "maxLength": 255, "description": "Entity ID (always required per item)", "example": "123" }, "entityType": { "type": "string", "enum": [ "contact", "company" ], "description": "Overrides default entityType" }, "signalTypes": { "type": "array", "items": { "type": "string" }, "description": "Overrides default signalTypes" }, "name": { "type": "string", "maxLength": 100, "description": "Overrides default name" } } } } } }, "CreateSubscriptionResponse": { "type": "object", "required": [ "total", "successful", "failed", "results" ], "properties": { "total": { "type": "integer", "example": 3 }, "successful": { "type": "integer", "example": 2 }, "failed": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/CreateSubscriptionSuccessResult" }, { "$ref": "#/components/schemas/CreateSubscriptionErrorResult" } ] } } } }, "CreateSubscriptionSuccessResult": { "type": "object", "required": [ "index", "success", "subscription" ], "properties": { "index": { "type": "integer", "example": 0 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "subscription": { "$ref": "#/components/schemas/SubscriptionWithoutSecret" } } }, "CreateSubscriptionErrorResult": { "type": "object", "required": [ "index", "success", "error" ], "properties": { "index": { "type": "integer", "example": 1 }, "success": { "type": "boolean", "enum": [ false ], "example": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "DUPLICATE_SUBSCRIPTION", "URL_VALIDATION_FAILED", "WEBHOOK_VERIFICATION_FAILED", "FORBIDDEN", "UNKNOWN_ERROR" ], "example": "DUPLICATE_SUBSCRIPTION" }, "message": { "type": "string", "example": "Subscription already exists for entity type 'contact' with entity ID '456'" } } } } }, "DeleteSubscriptionResponse": { "type": "object", "required": [ "total", "successful", "failed", "results" ], "properties": { "total": { "type": "integer", "example": 3 }, "successful": { "type": "integer", "example": 2 }, "failed": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DeleteSubscriptionSuccessResult" }, { "$ref": "#/components/schemas/DeleteSubscriptionErrorResult" } ] } } } }, "DeleteSubscriptionSuccessResult": { "type": "object", "required": [ "index", "success", "subscription" ], "properties": { "index": { "type": "integer", "example": 0 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "subscription": { "type": "object", "properties": { "id": { "type": "string", "example": "sub-123" }, "entityType": { "type": "string", "example": "contact" }, "entityId": { "type": "string", "example": "123" }, "name": { "type": "string", "example": "Contact Webhook" } } } } }, "DeleteSubscriptionErrorResult": { "type": "object", "required": [ "index", "success", "error" ], "properties": { "index": { "type": "integer", "example": 1 }, "success": { "type": "boolean", "enum": [ false ], "example": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "VALIDATION_ERROR", "FORBIDDEN", "UNKNOWN_ERROR" ], "example": "NOT_FOUND" }, "message": { "type": "string", "example": "Subscription with id 'sub-456' not found" } } } } }, "UpdateSubscriptionRequest": { "type": "object", "properties": { "signalTypes": { "type": "array", "items": { "type": "string" }, "description": "New signal types to subscribe to" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "New webhook URL" }, "name": { "type": "string", "maxLength": 100, "description": "New subscription name" }, "isActive": { "type": "boolean", "description": "Enable or disable subscription" }, "regenerateSecret": { "type": "boolean", "description": "Generate new webhook secret (secret will be returned in response)" } } }, "SubscriptionResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "entityType": { "type": "string", "enum": [ "contact", "company" ], "example": "contact" }, "entityId": { "type": "string", "example": "123456" }, "signalTypes": { "type": "array", "items": { "type": "string" }, "example": [ "promotion", "companyChange" ] }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/lusha" }, "name": { "type": "string", "example": "Contact Promotion Tracker" }, "isActive": { "type": "boolean", "example": true }, "secret": { "type": "string", "description": "Webhook secret (only returned during creation or regeneration)", "example": "whsec_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-01-14T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-01-14T10:00:00.000Z" } } }, "SubscriptionWithoutSecret": { "type": "object", "required": [ "id", "entityType", "entityId", "signalTypes", "url", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "entityType": { "type": "string", "enum": [ "contact", "company" ], "example": "contact" }, "entityId": { "type": "string", "example": "123456" }, "signalTypes": { "type": "array", "items": { "type": "string" }, "example": [ "promotion", "companyChange" ] }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/lusha" }, "name": { "type": "string", "example": "Contact Promotion Tracker" }, "isActive": { "type": "boolean", "example": true }, "blockReason": { "type": "string", "nullable": true, "description": "Reason subscription was disabled (null if active)", "example": "Max retries exceeded" }, "blockedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When subscription was disabled (null if active)", "example": "2026-01-14T10:00:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-01-14T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-01-14T10:00:00.000Z" } } }, "OptOutSubscriptionResponse": { "type": "object", "description": "Response body returned when an opt-out subscription is created successfully", "required": [ "id", "entityType", "entityId", "signalTypes", "url", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "example": "6a0ca910b402df368d2aff07" }, "entityType": { "type": "string", "enum": [ "contact" ], "example": "contact" }, "entityId": { "type": "string", "example": "431705" }, "signalTypes": { "type": "array", "items": { "type": "string" }, "example": [ "optOut" ] }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "name": { "type": "string", "example": "Account opt-out webhook" }, "isActive": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-05-19T18:16:48.360Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-05-19T18:16:48.360Z" } } }, "WebhookPayload": { "type": "object", "description": "Payload sent to your webhook URL when a signal is triggered", "required": [ "id", "type", "entityType", "entityId", "subscriptionId", "data", "timestamp", "billing" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique payload ID", "example": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c" }, "type": { "type": "string", "description": "Signal type that triggered the webhook", "example": "promotion" }, "entityType": { "type": "string", "enum": [ "contact", "company" ], "example": "contact" }, "entityId": { "type": "string", "example": "4158887495" }, "subscriptionId": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "data": { "type": "object", "description": "Signal-specific payload data. Structure varies by signal type." }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-01-14T16:16:35.841Z" }, "billing": { "type": "object", "required": [ "creditsCharged" ], "properties": { "creditsCharged": { "type": "integer", "example": 1 } } } } }, "AuditLogEntry": { "type": "object", "required": [ "id", "subscriptionId", "payloadId", "status", "url", "deliveredAt" ], "properties": { "id": { "type": "string", "example": "log-123" }, "subscriptionId": { "type": "string", "example": "sub-123" }, "payloadId": { "type": "string", "example": "payload-456" }, "status": { "type": "string", "enum": [ "success", "failed", "permanent_failure" ], "example": "success" }, "statusCode": { "type": "integer", "example": 200 }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "deliveredAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" }, "durationMs": { "type": "integer", "example": 150 }, "error": { "type": "string", "nullable": true, "example": null } } }, "PaginationResponse": { "type": "object", "required": [ "total", "size", "page", "hasMore" ], "properties": { "total": { "type": "integer", "example": 100 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "hasMore": { "type": "boolean", "example": true } } }, "AuditLogsResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "pagination": { "$ref": "#/components/schemas/PaginationResponse" } } }, "AuditLogStatsResponse": { "type": "object", "required": [ "total", "success", "failed", "successRate" ], "properties": { "total": { "type": "integer", "example": 1000 }, "success": { "type": "integer", "example": 950 }, "failed": { "type": "integer", "example": 50 }, "successRate": { "type": "string", "example": "95.00%" } } }, "SubscriptionListResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionWithoutSecret" } }, "pagination": { "$ref": "#/components/schemas/PaginationResponse" } } }, "CreateOptOutSubscriptionRequest": { "type": "object", "required": [ "entityType", "url" ], "description": "Request body for creating an opt-out webhook subscription", "properties": { "entityType": { "type": "string", "enum": [ "contact" ], "description": "Entity type for opt-out subscriptions. Currently only `contact` is supported.", "example": "contact" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Your webhook endpoint URL (HTTPS required in production)", "example": "https://example.com/webhook" }, "name": { "type": "string", "maxLength": 100, "description": "Descriptive name for this subscription", "example": "Account opt-out webhook" } } }, "OptOutDatapoint": { "type": "object", "description": "A single contact data point that must be removed following an opt-out request", "required": [ "datapointId", "datapointType" ], "properties": { "datapointId": { "type": "string", "description": "The actual value of the data point (phone number or email address)", "example": "+14155550199" }, "datapointType": { "type": "string", "enum": [ "phone", "email" ], "description": "Type of data point", "example": "phone" } } }, "OptOutWebhookPayload": { "type": "object", "description": "Payload delivered to your opt-out webhook URL when a contact requests data removal.\n\nYour system must process this payload to remove the listed data points from any internal records, CRM entries, or outreach sequences.\n", "required": [ "contactId", "fullName", "contactOptOutDate", "contactExposureDate", "datapoints" ], "properties": { "contactId": { "type": "string", "description": "Lusha contact ID of the person who opted out", "example": "987654321" }, "fullName": { "type": "string", "description": "Full name of the contact", "example": "Jane Doe" }, "companyName": { "type": "string", "description": "Company the contact is associated with", "example": "Acme Corp" }, "jobTitle": { "type": "string", "description": "Job title of the contact", "example": "Director of Product" }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL of the contact", "example": "https://www.linkedin.com/in/jane-doe" }, "contactOptOutDate": { "type": "string", "description": "Timestamp when the contact submitted their opt-out request (UTC)", "example": "2026-04-22 14:32:11.412" }, "contactExposureDate": { "type": "string", "description": "Timestamp when this contact's data was first exposed to your account (UTC)", "example": "2025-08-03 09:15:47" }, "datapoints": { "type": "array", "description": "List of specific data points (emails and/or phones) that must be removed", "items": { "$ref": "#/components/schemas/OptOutDatapoint" }, "example": [ { "datapointId": "+14155550199", "datapointType": "phone" }, { "datapointId": "jane.doe@acme.com", "datapointType": "email" } ] }, "partnerClientId": { "type": "string", "nullable": true, "description": "Your internal client/tenant identifier, if provided when the contact data was originally revealed. Useful for multi-tenant setups to route the removal to the correct system.\n", "example": "acme-crm-tenant-42" } } }, "TestSubscriptionResponse": { "type": "object", "required": [ "subscriptionId", "url", "mode", "isSuccess", "timestamp" ], "properties": { "subscriptionId": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "subscriptionName": { "type": "string", "example": "My Test Webhook" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "mode": { "type": "string", "enum": [ "direct", "kafka", "full" ], "example": "full" }, "flowCheck": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer", "example": 200 }, "durationMs": { "type": "integer", "example": 150 } } }, "testPayload": { "type": "object", "properties": { "entityType": { "type": "string", "example": "contact" }, "signalType": { "type": "string", "example": "promotion" }, "data": { "type": "object" } } }, "isSuccess": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" } } }, "V3ConversationsSearchRequest": { "type": "object", "description": "All properties are optional. Supply `query` for keyword mode (structural filters are then ignored), or omit `query` and supply structural filters for filter mode. An empty body returns the first page of the account's conversations.\n", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text search over transcript content. When present, the structural filters below are ignored.", "example": "pricing objection" }, "conversationIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "Return only these conversations. IDs that don't exist, are still processing, or belong to another account are omitted from the response rather than erroring." }, "dateFrom": { "type": "string", "format": "date", "description": "Earliest meeting date, inclusive (YYYY-MM-DD).", "example": "2026-01-01" }, "dateTo": { "type": "string", "format": "date", "description": "Latest meeting date, inclusive (YYYY-MM-DD).", "example": "2026-03-31" }, "contactNames": { "type": "array", "items": { "type": "string" }, "description": "Partial, case-insensitive match on participant names. Multiple values are ORed.", "example": [ "Jane Doe" ] }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Company domains of the external participants (e.g. acme.com). Matches on domain, not display name. Multiple values are ORed.", "example": [ "acme.com" ] }, "meetingTitles": { "type": "array", "items": { "type": "string" }, "description": "Partial, case-insensitive match on the meeting title. Multiple values are ORed.", "example": [ "Quarterly review" ] }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, starting at 1.", "example": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Conversations per page. Values above 100 are rejected with 400 (not silently clamped).", "example": 25 } } }, "ConversationActionItem": { "type": "object", "properties": { "text": { "type": "string", "example": "Send the revised pricing sheet" }, "owner": { "type": "string", "example": "Sam Rep" }, "dueDate": { "type": "string", "format": "date", "nullable": true, "description": "May be null.", "example": "2026-03-19" } } }, "ConversationSeverityItem": { "type": "object", "properties": { "text": { "type": "string", "example": "Budget approval is still pending" }, "severity": { "type": "string", "nullable": true, "description": "Null means the pipeline did not assess severity. Do not read it as \"low\".", "example": "high" } } }, "ConversationCompetitor": { "type": "object", "properties": { "name": { "type": "string", "example": "Competitor Inc" }, "context": { "type": "string", "example": "Mentioned as incumbent" }, "sentiment": { "type": "string", "nullable": true, "description": "May be null.", "example": "negative" } } }, "ConversationSummary": { "type": "object", "nullable": true, "description": "Post-call analysis, or null while it is still being produced.", "properties": { "text": { "type": "string", "description": "Narrative summary.", "example": "The team walked through the pricing tiers." }, "keyHighlights": { "type": "array", "items": { "type": "string" }, "description": "Notable moments.", "example": [ "Budget confirmed for Q3" ] }, "actionItems": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationActionItem" } }, "nextSteps": { "type": "array", "items": { "type": "string" }, "example": [ "Schedule a technical deep dive" ] }, "risks": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationSeverityItem" } }, "objections": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationSeverityItem" } }, "competition": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationCompetitor" } } } }, "ConversationCoachingSection": { "type": "object", "properties": { "section": { "type": "string", "example": "discovery" }, "score": { "type": "number", "nullable": true, "description": "May be null.", "example": 72 }, "whatHappened": { "type": "string", "example": "The rep opened with a clear agenda." }, "whatToKeep": { "type": "array", "items": { "type": "string" }, "example": [ "Strong discovery questions" ] }, "whatToImprove": { "type": "array", "items": { "type": "string" }, "example": [ "Confirm the decision process earlier" ] } } }, "ConversationCoaching": { "type": "object", "nullable": true, "description": "Coaching analysis, or null while it is still being produced.", "properties": { "overallScore": { "type": "number", "description": "Overall coaching score, 0–100.", "example": 68 }, "likelihoodOfSale": { "type": "number", "nullable": true, "description": "Predicted likelihood of closing, 0–100. May be null.", "example": 45 }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationCoachingSection" } }, "notes": { "type": "string", "description": "Free-text coaching notes.", "example": "Focus on quantifying impact." } } }, "ConversationChapter": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "title": { "type": "string", "example": "Introductions" }, "startTime": { "type": "string", "description": "Offset from the start of the recording.", "example": "00:00:00" }, "endTime": { "type": "string", "description": "Offset from the start of the recording.", "example": "00:04:12" }, "summary": { "type": "string", "example": "Participants introduced themselves." } } }, "ConversationParticipant": { "type": "object", "properties": { "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "example": "jane@acme.com" }, "role": { "type": "string", "example": "VP Sales" }, "isInternal": { "type": "boolean", "example": false } } }, "ConversationCompany": { "type": "object", "description": "External participants' company. Either field may be null.", "properties": { "name": { "type": "string", "nullable": true, "example": "Acme Inc" }, "domain": { "type": "string", "nullable": true, "example": "acme.com" } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation identifier. Pass this to Get Conversation Transcript.", "example": "8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90" }, "title": { "type": "string", "description": "Meeting title.", "example": "Acme <> Lusha - Quarterly review" }, "date": { "type": "string", "format": "date", "description": "Meeting date (YYYY-MM-DD).", "example": "2026-03-12" }, "startTime": { "type": "string", "format": "date-time", "description": "Meeting start time (ISO 8601).", "example": "2026-03-12T14:00:00Z" }, "durationSeconds": { "type": "number", "description": "Meeting length in seconds.", "example": 1830 }, "durationFormatted": { "type": "string", "description": "Human readable length, e.g. 30m 30s.", "example": "30m 30s" }, "meetingType": { "type": "string", "nullable": true, "description": "Meeting type as classified by the analysis pipeline.", "example": "discovery" }, "isExternal": { "type": "boolean", "nullable": true, "description": "true when at least one participant is outside your account.", "example": true }, "company": { "$ref": "#/components/schemas/ConversationCompany" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationParticipant" } }, "topicLabels": { "type": "array", "items": { "type": "string" }, "description": "Topics detected in the conversation.", "example": [ "pricing", "security" ] }, "summary": { "$ref": "#/components/schemas/ConversationSummary" }, "coaching": { "$ref": "#/components/schemas/ConversationCoaching" }, "chapters": { "type": "array", "description": "Timestamped chapters. Empty until the analysis pipeline has run.", "items": { "$ref": "#/components/schemas/ConversationChapter" } } } }, "ConversationPage": { "type": "object", "description": "Paging envelope for Search Conversations.", "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 25 }, "totalItems": { "type": "integer", "example": 137 }, "totalPages": { "type": "integer", "example": 6 } } }, "V3ConversationsSearchResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "description": "Correlation / request id for support and tracing.", "example": "3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90" }, "conversations": { "type": "array", "description": "Matching conversations. In keyword mode they are ordered by content relevance.", "items": { "$ref": "#/components/schemas/Conversation" } }, "page": { "$ref": "#/components/schemas/ConversationPage" }, "billing": { "$ref": "#/components/schemas/V3Billing" } } }, "ConversationTranscriptSegment": { "type": "object", "properties": { "speaker": { "type": "string", "description": "Speaker name as resolved by the meeting provider.", "example": "Jane Doe" }, "side": { "type": "string", "nullable": true, "description": "Which side of the conversation the speaker is on, e.g. internal / external.", "example": "external" }, "text": { "type": "string", "description": "What was said.", "example": "We need to understand the pricing tiers before we commit." }, "startTime": { "type": "string", "description": "Offset from the start of the recording.", "example": "00:12:04" }, "endTime": { "type": "string", "description": "Offset from the start of the recording.", "example": "00:12:19" } } }, "V3ConversationTranscriptResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "description": "Correlation / request id for support and tracing.", "example": "3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90" }, "conversationId": { "type": "string", "description": "The conversation this transcript belongs to.", "example": "8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90" }, "segments": { "type": "array", "description": "Chronologically ordered segments.", "items": { "$ref": "#/components/schemas/ConversationTranscriptSegment" } }, "billing": { "$ref": "#/components/schemas/V3Billing" } } } } } }