{
"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| [**Enrichment**](#tag/Enrichment) | Search and enrich contacts and companies by identifier |\n| [**Prospecting**](#tag/Prospecting) | Filter-based search across contacts and companies |\n| [**Lookalikes**](#tag/Lookalikes) | AI-powered recommendations for similar contacts and companies |\n| [**Signals**](#tag/Signals) | Real-world activity data for contacts and companies |\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## 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## 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 to ensure fair usage and protect against excessive load.\n\n| Scope | Limit |\n|-------|-------|\n| General endpoints | 25 requests per second |\n| Credit Usage API | 5 requests per minute |\n\n> Rate limits may vary by account type and plan. Contact your account manager or [Lusha support](mailto:support@lusha.com) if you frequently hit limits.\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**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": "Enrichment",
"description": "**Enrichment APIs:** Search and enrich contacts and companies.\n\nThe V3 API uses a **search-then-enrich** pattern:\n\n1. **Search** — Find contacts or companies by identifier. Returns previews with non-PII data and a `has` field listing available data points.\n2. **Enrich** — Reveal full data (emails, phones, firmographics) using IDs from search.\n\nYou can also use **Search and Enrich** to combine both steps in a single call.\n\n**Supported identifiers**\n- Contacts: `id`, LinkedIn URL, email, or name + company\n- Companies: `id`, name, or domain\n\nOptionally filter results by signal types using the `signals` parameter (see **Signals** section).\n\n**Billing:** Search uses a capture/charge model (`api_search`). Enrich charges per data point revealed (`revealEmail`, `revealPhone`, `reveal_company`).\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\nResults are paginated: up to **1,000 pages x 50 results = 50,000 results** per query. Responses use the same `ContactPreview` and `CompanyPreview` structures as the search endpoints.\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",
"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**Contact signal types:** `promotion`, `companyChange`, `allSignals`\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\nCredits are charged per matched signal per result via `showSignalsContact` or `showSignalsCompany`.\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": [
"Enrichment"
],
"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": [
"Enrichment"
],
"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> **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",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V3ContactsEnrichRequest"
},
"example": {
"ids": [
"4389064654",
"4389064624"
],
"reveal": [
"emails",
"phones"
]
}
}
}
},
"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": [
"Enrichment"
],
"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": [
"Enrichment"
],
"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": [
"Enrichment"
],
"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\n\n> **Billing:** Charged per successful result via the `reveal_company` action.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V3CompaniesEnrichRequest"
},
"example": {
"ids": [
"16303253",
"12790225"
],
"reveal": [
"employeesByLocation",
"employeesByDepartment",
"employeesBySeniority",
"competitors",
"intent"
]
}
}
}
},
"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"
},
"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"
]
},
{
"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"
}
]
}
],
"billing": {
"creditsCharged": 10,
"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-and-enrich": {
"post": {
"tags": [
"Enrichment"
],
"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\n> **Billing:** Same as Enrich Companies — charged per successful result via the `reveal_company` action.\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"
}
],
"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"
}
]
}
],
"billing": {
"creditsCharged": 3,
"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/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\nResults are paginated up to 50,000 total (1,000 pages × 50 results). Use 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",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V3ProspectingContactsRequest"
},
"example": {
"pagination": {
"page": 0,
"size": 50
},
"filters": {
"contacts": {
"include": {
"departments": [
"Sales"
],
"locations": [
{
"country": "United States"
}
],
"existingDataPoints": [
"work_email"
]
}
},
"companies": {
"include": {
"locations": [
{
"country": "United States"
}
]
},
"exclude": {
"domains": [
"competitor.com"
]
}
}
},
"options": {
"maxContactsPerCompany": 25,
"includePartialProfiles": true,
"excludeDnc": false
}
}
}
}
},
"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
},
"results": [
{
"id": "670138733",
"firstName": "Ting",
"lastName": "Tsou"
}
],
"billing": {
"creditsCharged": 0,
"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)\n\nResults are paginated up to 50,000 total. Use 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",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V3ProspectingCompaniesRequest"
},
"example": {
"pagination": {
"page": 0,
"size": 25
},
"filters": {
"companies": {
"include": {
"sizes": [
{
"min": 100,
"max": 1000
}
],
"revenues": [
{
"min": 10000000
}
],
"locations": [
{
"country": "United States"
}
],
"technologies": [
"React",
"Node.js"
],
"technologiesCondition": "or",
"mainIndustriesIds": [
1,
5
],
"intentTopics": [
"Cloud Migration"
],
"signals": {
"types": [
"headcountIncrease3m",
"surgeInHiring"
],
"startDate": "2025-01-01"
}
},
"exclude": {
"domains": [
"competitor.com"
]
}
}
},
"options": {
"maxContactsPerCompany": 10,
"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
},
"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 5-100 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**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",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactLookalikesRequest"
},
"examples": {
"firstRequest": {
"summary": "First request (server generates dedupeSessionId)",
"value": {
"seeds": {
"linkedinUrls": [
"https://www.linkedin.com/in/orit-shilvock-6243bb5"
],
"emails": [
"gal.ashkelon@lusha.com"
],
"ids": [
"1234"
]
},
"exclude": {
"emails": [
"existing@customer.com"
]
},
"limit": 25
}
},
"secondRequest": {
"summary": "Second request (get more using dedupeSessionId)",
"value": {
"dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
"seeds": {
"linkedinUrls": [
"https://www.linkedin.com/in/shmulikwillinger"
]
},
"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 5-100 seed companies via domains or LinkedIn URLs. The API returns companies with similar size, industry, and profile.\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",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompanyLookalikesRequest"
},
"examples": {
"firstRequest": {
"summary": "First request (server generates dedupeSessionId)",
"value": {
"seeds": {
"domains": [
"sap.com",
"oracle.com"
],
"linkedinUrls": [
"https://www.linkedin.com/company/google"
]
},
"exclude": {
"domains": [
"existingcustomer.com"
]
},
"limit": 100
}
},
"secondRequest": {
"summary": "Second request (get more using dedupeSessionId)",
"value": {
"dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
"seeds": {
"domains": [
"sap.com"
]
},
"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/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",
"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",
"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",
"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
}
]
}
}
}
},
"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",
"parameters": [
{
"name": "filterType",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"newsEventTypes",
"hiringByDepartments",
"hiringByLocations"
]
}
},
{
"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/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"
}
}
}
}
},
"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"
}
},
"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 or V3 access not enabled",
"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"
}
}
}
}
}
},
"NotFound": {
"description": "Not found - resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"statusCode": 404,
"message": "Resource not found"
}
}
}
},
"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"
],
"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"
}
}
},
"V3Range": {
"type": "object",
"description": "Numeric range filter",
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"example": 100
},
"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",
"example": 150
}
}
},
"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"
}
}
}
]
},
"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",
"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"
},
"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.\n",
"example": [
"alternativeName",
"alternativeDomains",
"description",
"companyType",
"yearFounded",
"subIndustry",
"specialities",
"sicCodes",
"naicsCodes",
"additionalLocations",
"linkedinFollowers",
"popularityTier",
"logoUrl",
"employeesByDepartment",
"employeesByLocation",
"employeesBySeniority",
"competitors",
"businessModel",
"phones",
"emails",
"keywords",
"socialLinks"
]
},
"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
}
]
},
"signalTypes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"headcountIncrease3m"
]
},
"error": {
"$ref": "#/components/schemas/V3ItemError"
}
}
},
"V3CompanyLocation": {
"type": "object",
"properties": {
"city": {
"type": "string",
"example": "London"
},
"state": {
"type": "string",
"example": "England"
},
"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"
}
}
},
"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"
}
},
"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"
}
}
},
"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": {
"$ref": "#/components/schemas/ContactIdentifiersBatch"
},
"exclude": {
"$ref": "#/components/schemas/ContactIdentifiersBatch"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"example": 25
}
}
},
"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
]
}
},
"nullable": true
},
"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"
},
"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": {
"$ref": "#/components/schemas/CompanyIdentifiersBatch"
},
"exclude": {
"$ref": "#/components/schemas/CompanyIdentifiersBatch"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"example": 25
}
}
},
"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"
},
"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"
}
}
}
}
},
"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"
}
}
}
}
},
"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"
]
},
"topicCountThreshold": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3Range"
}
},
"sicCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"naicsCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"funding": {
"type": "object",
"properties": {
"isIpo": {
"type": "boolean"
},
"ranges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3Range"
}
},
"types": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Series B",
"Series C"
]
},
"investors": {
"type": "array",
"items": {
"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"
]
},
"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"
]
},
"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"
}
}
}
}
}
}
}
},
"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
}
}
},
"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"
},
"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",
"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",
"example": "2025-01-01"
},
"maxResultsPerSignal": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10
}
}
},
"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"
}
},
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string"
},
"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"
}
}
}
},
"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"
]
}
}
},
"V3ContactsEnrichResponse": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3EnrichedContact"
}
},
"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"
]
},
"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",
"example": [
"employeesByDepartment",
"employeesByLocation",
"employeesBySeniority",
"competitors",
"intent"
]
}
}
},
"V3CompaniesEnrichResponse": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3EnrichedCompany"
}
},
"billing": {
"$ref": "#/components/schemas/V3Billing"
}
}
},
"V3CompaniesSearchAndEnrichRequest": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3CompanySearchItem"
},
"minItems": 1,
"maxItems": 100
},
"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"
},
"options": {
"type": "object",
"properties": {
"maxContactsPerCompany": {
"type": "integer"
},
"includePartialProfiles": {
"type": "boolean",
"default": true
},
"excludeDnc": {
"type": "boolean"
}
}
}
}
},
"V3ProspectingContactsResponse": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3ContactPreview"
}
},
"pagination": {
"$ref": "#/components/schemas/V3PaginationResponse"
},
"billing": {
"$ref": "#/components/schemas/V3Billing"
}
}
},
"V3ProspectingCompaniesRequest": {
"type": "object",
"required": [
"pagination",
"filters"
],
"properties": {
"pagination": {
"$ref": "#/components/schemas/V3PaginationRequest"
},
"filters": {
"type": "object",
"required": [
"companies"
],
"properties": {
"companies": {
"type": "object",
"required": [
"include"
],
"properties": {
"include": {
"$ref": "#/components/schemas/V3CompanyProspectingFilters"
},
"exclude": {
"$ref": "#/components/schemas/V3CompanyProspectingFilters"
}
}
}
}
},
"options": {
"type": "object",
"properties": {
"maxContactsPerCompany": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"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"
},
"billing": {
"$ref": "#/components/schemas/V3Billing"
}
}
},
"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",
"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",
"limit",
"offset",
"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"
}
}
}
}
}
}