{ "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": "Lusha provides a RESTful API that allows you to query a comprehensive dataset of business profiles and company information.\nIt is designed for teams building prospecting, enrichment, automation, and analytics workflows that require accurate, continuously updated business data. The API supports both real-time and bulk use cases and is suitable for production environments.\nUse the Lusha API to search for new prospects, enrich existing records, react to real-world changes, and expand coverage using lookalike recommendations. \n\n*All API requests should be made over HTTPS (SSL), and the response bodies are delivered in JSON format.*\n---\n \n
\n
\n \n \n
\n

\n Person\n

\n \n \n
https://api.lusha.com/v2/person
\n \n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Form enrichment
    • \n
  • • CRM completion
    • \n
  • • Outbound personalization
    • \n
\n
\n
\n\n \n
\n

\n Company\n

\n \n \n
https://api.lusha.com/v2/company
\n \n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Account enrichment
    • \n
  • • Routing, scoring, territory logic
    • \n
  • • Market analysis & segmentation
    • \n
\n
\n
\n\n \n
\n

\n Signals\n

\n \n \n
https://api.lusha.com/v2/signals
\n \n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Job change tracking
    • \n
  • • Company updates signals
    • \n
  • • News event alerts
    • \n
\n
\n
\n\n \n
\n

\n Lookalikes\n

\n \n \n
https://api.lusha.com/v3/lookalike
\n \n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Market expansion
    • \n
  • • Similar account discovery
    • \n
  • • Prospect recommendations
    • \n
\n
\n
\n\n \n
\n

\n Filters\n

\n \n
\n\n \n
\n

\n Account\n

\n \n
\n\n
\n
\n\n \n
\n
\n
\n
\n Webhooks API\n NEW\n
\n

\n Subscribe to real-time notifications when contacts change jobs or companies experience key business events.\n

\n \n View Documentation →\n \n
\n
\n
\n\n\n\n\n---\n**Data Source and Privacy**\n\nPlease note that **Lusha is a search platform**, meaning the data provided is not created or directly managed by us. Instead, it is retrieved from publicly available sources and through contributions from trusted business partners.\n\nFor more information on how we collect, use, and handle business profiles, please refer to our [Privacy Policy](https://lusha.com/legal/privacy-notice/).\n----\n## Authentication\nAPI keys are required for all API and MCP requests and are tied to your Lusha account and plan. To access the Lusha API, you must authenticate your requests using your API key. This key is unique to your account and is used to identify your usage of the API.\nHow to Authenticate:\n\n When making an API call, include your API key in the `api_key` header of the\nrequest.\n> You can generate and retrieve your API key [here](https://dashboard.lusha.com/enrich/api).\nAPI keys should be stored securely and used only in server-side environments.\n\n---\n\n### Rate Limiting\nLusha API enforces rate limiting to ensure fair usage and protect against excessive load.\n\n- **General Rate Limit**: You can make up to 25 requests per second to each API endpoint\n- **Credit Usage API**: Has a specific rate limit of 5 requests per minute\n> **Note**: Rate limits may vary based on your account type and subscription plan. \n If you're encountering rate limit issues frequently, please consult with your \n account manager or Lusha support team to discuss your specific needs.\n\n\n**Rate Limit Headers**\n\nTo monitor your current rate limit status, check the HTTP response headers in your API calls:\n\n| Header | Description |\n|--------|-------------|\n| `x-rate-limit-daily` | The total number of requests allowed per day under your current plan |\n| `x-daily-requests-left` | The number of requests remaining in your daily quota |\n| `x-daily-usage` | The number of requests you have made in the current daily period |\n| `x-rate-limit-hourly` | The total number of requests allowed per hour under your current plan |\n| `x-hourly-requests-left` | The number of requests remaining in your hourly quota |\n| `x-hourly-usage` | The number of requests you have made in the current hourly period |\n| `x-rate-limit-minute` | The total number of requests allowed per minute under your current plan |\n| `x-minute-requests-left` | The number of requests remaining in your current minute window |\n| `x-minute-usage` | The number of requests you have made in the current minute window |\n\n**Notes on API Rate Limiting**\n- If you exceed the rate limit, the API will return a 429 (Too Many Requests) error.\n- To ensure a smooth experience, respect the rate limits defined by your subscription tier.\n- Daily limits vary based on your billing plan — higher tiers have higher quotas.\n- You can programmatically track your usage through these response headers:\n - `X-RateLimit-Remaining-Daily`\n - `X-RateLimit-Reset-Daily`\n- It is strongly recommended to implement logic that:\n - Monitors these headers\n - Pauses or retries requests accordingly\n - Helps avoid hitting the limit and ensures reliable operation\n\n---\n## Error Codes\nLusha API uses standard HTTP response codes to indicate the status of your request. These codes help you understand whether the request was successful or if there was an issue.\n\n| Status Code | Name | Description |\n|-------------|------|-------------|\n| **200** | OK | Successful request |\n| **400** | Bad Request | Badly formatted request |\n| **401** | Unauthorized | The API key is invalid |\n| **402** | Payment Required | Your account requires payment |\n| **403** | Forbidden | Your account is not active. Please reach out to support at *support@lusha.com* for assistance |\n| **403** | Forbidden | Your pricing version does not support requesting individual datapoints [revealEmails, revealPhones] |\n| **404** | Not Found | The requested endpoint was not found |\n| **412** | Precondition Failed | The request failed due to invalid syntax that was provided. Please make sure to send a full name field that contains a valid first & last name |\n| **429** | Too Many Requests | You've reached your trial limit, please contact support for upgrade |\n| **429** | Too Many Requests | Daily API quota limit exceeded. Limit X calls per day |\n| **429** | Too Many Requests | Hourly API rate limit exceeded. Limit: X calls per hour. Reset in X seconds |\n| **451** | Unavailable For Legal Reasons | We are unable to process this contact request due to our GDPR regulations |\n| **499** | Client Closed Request | Request failed due to request timeout |\n| **5XX** | Server Error | There's a problem on Lusha's end |\n\n\n**Error Response Format**\n\nIn case of an error, the response body will contain details about the error:\n\n```json\n{\n \"error\": {\n \"code\": 400,\n \"message\": \"Invalid request parameters\"\n }\n}\n```\n\nHandling errors\n\n- Always ensure your API key is correct and valid\n- Pay attention to the specific error message and code to troubleshoot issues efficiently\n- Implement proper error handling and retry logic in your application\n- For 5XX errors, implement exponential backoff before retrying\n\n ---\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": "**What is enrichment?**:\n\nEnrichment is the process of adding missing or updated data to existing contact or company records.\n\nUse enrichment to:\n- Complete CRM records\n- Improve outbound accuracy and deliverability\n- Keep records current as people and companies change\n\n> Enrichment can be performed in real time or in bulk, depending on the endpoint and use case.\n\n**Available enrichment APIs**\n\nPerson enrichment:\n- [**Search single contact**](/apis/openapi/enrichment/searchsinglecontact) - Enrich one contact at a time\n- [**Search multiple contacts**](/apis/openapi/enrichment/searchmultiplecontacts) - Bulk enrich contacts\n\nCompany enrichment:\n- [**Search a single company**](/apis/openapi/enrichment/searchsinglecompanyv2) - Enrich one company at a time\n- [**Search multiple companies**](/apis/openapi/enrichment/searchmultiplecompaniesv2) - Bulk enrich companies" }, { "name": "Prospecting - Search & Enrich", "description": "With Lusha's Prospecting API, you can query Lusha's extensive database based on specific criteria (such as job title, seniority, location, and more) to retrieve detailed contact and company information.\n\nThe Prospecting API is designed to help you generate new records (contacts or companies) for your CRM system, using filters that align with your Ideal Customer Profile (ICP).\n\nThis process involves three main steps:\n\n| Step | API | Description |\n|------|-----|-------------|\n| 1 | **Filters API** | Apply filters to refine your search *(Check available filters under [Contact](/apis/openapi/contact-filters) and [Company](/apis/openapi/company-filters) Filters)*|\n| 2 | **Search API** | Query [Contacts](/apis/openapi/prospecting-search-and-enrich/searchprospectingcontacts) or [Companies](/apis/openapi/prospecting-search-and-enrich/searchprospectingcompanies) using the available filters |\n| 3 | **Enrich API** | Get full details of [Contacts](/apis/openapi/prospecting-search-and-enrich/enrichprospectingcontacts) and [Companies](/apis/openapi/prospecting-search-and-enrich/enrichprospectingcompanies) from the search results |\n", "x-tag-expanded": true }, { "name": "Contact Filters", "description": "Available filters for contact searches", "x-parent-tag": "Prospecting" }, { "name": "Company Filters", "description": "Available filters for company searches", "x-parent-tag": "Prospecting" }, { "name": "Signals", "description": "With Lusha’s Signals API, you can enrich your contacts and companies with timely insights that highlight key account and prospect changes. Signals help you identify moments of opportunity - from job moves and promotions to company growth and new initiatives - so you can engage prospects and customers at exactly the right time. Easily integrate signal data into enrichment flows, CRM systems, or automation workflows to keep pipelines and customer records always up to date.", "x-tag-expanded": true }, { "name": "Lookalikes", "description": "Lusha's Lookalikes API helps you discover similar contacts and companies based on your existing data. Get AI-powered suggestions for new prospects that match your ideal customer profile.\n\n[**Contact Lookalikes**](/apis/openapi/lookalikes/getcontactlookalikes) - Find similar contacts based on role, seniority, and industry patterns.\n\n[**Company Lookalikes**](/apis/openapi/lookalikes/getcompanylookalikes)- Discover companies with similar firmographics and characteristics.", "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\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" }, { "name": "Account Management", "description": "Manage your account and monitor usage.\n\nUse this endpoint to:\n- Monitor credit usage\n- Understand consumption patterns\n- Align API usage with plan limits\n- Support governance and production operations\n\nAccount-level insights are especially important for teams running Lusha at scale or across multiple systems.\n" } ], "paths": { "/v2/person": { "get": { "tags": [ "Enrichment" ], "summary": "Search Single Contact", "description": "Find and enrich a single contact using various search criteria. You can search by name, email, \nLinkedIn URL, or Person Id.\n>##### Endpoint\n ```\nGET https://api.lusha.com/v2/person\n ```\n\n\n>##### Search Requirements\n \nYou must provide either:\n- `personId` OR\n- `email` OR\n- `linkedinUrl` OR\n- `firstName` AND `lastName` AND (`companyName` OR `companyDomain`)\n\n>##### Notes: \n- Provide as much information as possible for better results\n- Using `personId` provides the most direct way to retrieve contact information, as it uniquely identifies a contact in Lusha's database.\n- Use `refreshJobInfo=true` to get the latest employment data\n- Use `filterBy` parameter to specify what contact details you need\n- Include the `signals` parameter to retriever contact signals (If no signals data is found for the specified period, the `signals` object will be empty but still present in the response.)\n - When requesting signals, you can optionally specify a start date using `signalsStartDate`.\n - Signals data is optional. If you don't include the `signals` parameter, no signals data will be returned.\n\n \n\n---\n\n⚠️ **Important Notice - Unified Credits Plan Required**\n\n| Parameter | Requirement |\n|-----------|-------------|\n| `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan |\n| Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error |\n| Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available |\n\n---\n", "operationId": "searchSingleContact", "parameters": [ { "$ref": "#/components/parameters/firstName" }, { "$ref": "#/components/parameters/lastName" }, { "$ref": "#/components/parameters/personId" }, { "$ref": "#/components/parameters/companyName" }, { "$ref": "#/components/parameters/companyDomain" }, { "$ref": "#/components/parameters/email" }, { "$ref": "#/components/parameters/linkedinUrl" }, { "$ref": "#/components/parameters/refreshJobInfo" }, { "$ref": "#/components/parameters/filterBy" }, { "$ref": "#/components/parameters/revealEmails" }, { "$ref": "#/components/parameters/revealPhones" }, { "$ref": "#/components/parameters/signals" }, { "$ref": "#/components/parameters/signalsStartDate" }, { "$ref": "#/components/parameters/partialProfile" } ], "responses": { "200": { "description": "Successfully found contact information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleContactResponse" }, "examples": { "successful_response": { "summary": "Successful contact lookup", "value": { "contact": { "error": null, "isCreditCharged": false, "data": { "companyId": 33222678, "firstName": "Dustin", "lastName": "Moskovitz", "fullName": "Dustin Moskovitz", "emailAddresses": [ { "address": "dustin@lusha.com", "type": "work", "emailConfidence": "A+", "updateDate": "2024-01-15" } ], "phoneNumbers": [ { "number": "+1-555-123-4567", "phoneType": "Mobile", "doNotCall": false, "updateDate": "2024-01-15" } ], "location": { "country": "United States", "countryIso2": "US", "continent": "North America", "rawLocation": "Boston, MA, US", "city": "Boston", "state": "Massachusetts", "stateCode": "MA", "isEuContact": false }, "jobTitle": { "seniority": "Executive", "title": "CEO", "departments": [ "Executive" ] }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/dustin/", "xUrl": "https://twitter.com/dustin" }, "jobStartDate": "2020-01-01", "personId": 123456, "updateDate": "2024-01-15", "linkedinFollowersCount": 12500, "linkedinConnectionsCount": 500, "linkedinCertifications": [ { "companyName": "Microsoft", "title": "Microsoft Certified: Azure Fundamentals", "dateYear": 2020, "dateMonth": 6, "verifyUrl": "https://www.youracclaim.com/badges/5ccf865c-dd6e-4dcc-9184-c8999d31f83d" } ], "linkedinCourses": [ { "title": "Advanced Leadership Strategies", "companyName": "LinkedIn Learning" } ], "linkedinAwards": [ { "title": "Tech Leader of the Year", "companyName": "Tech Awards Council", "dateYear": 2023, "summary": "Recognition for outstanding leadership in technology innovation" } ], "linkedinSkills": [ "Strategic Planning", "Team Leadership", "Product Development" ], "company": { "name": "Lusha", "description": "Lusha is the sales intelligence platform designed to help businesses get their next customers.", "domains": { "homepage": "https://www.lusha.com", "email": "lusha.com" }, "fqdn": "lusha.com", "location": { "country": "United States", "countryIso2": "US", "continent": "North America", "rawLocation": "Boston, MA, US", "city": "Boston", "state": "Massachusetts" }, "companySize": [ 201, 500 ], "revenueRange": [ 10000000, 50000000 ], "logoUrl": "https://logo.lusha.co/logo.jpg", "social": { "linkedin": "https://linkedin.com/company/lusha", "crunchbase": "https://crunchbase.com/company/lusha" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/GDPRRestricted" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Enrichment" ], "summary": "Search Multiple Contacts", "description": "Enrich multiple contacts in a single request. This endpoint allows you to submit a list of contacts \nand receive enriched data for each one, including company information.\n\n>##### Endpoint:\n ```\nPOST https://api.lusha.com/v2/person\n ```\n\n\n>##### Notes\n - You can process up to 100 contacts per request.\n - Using `personId` provides the most direct way to retrieve contact information.\n - At least one of `email`, `linkedinUrl`, or `company`/`domain` with `fullName` is required. \n\n \n---\n\n⚠️ **Important Notice - Unified Credits Plan Required**\n\n| Parameter | Requirement |\n|-----------|-------------|\n| `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan |\n| Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error |\n| Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available |\n\n---\n", "operationId": "searchMultipleContacts", "requestBody": { "required": true, "description": "The list of contacts to enrich", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchBulkContactsRequest" }, "examples": { "successful_response": { "summary": "Successful contact lookup", "value": { "contacts": [ { "contactId": "1", "personId": "4183886134", "fullName": "John Doe", "email": "john@example.com", "companies": [ { "name": "Example Corp", "domain": "example.com", "isCurrent": true } ] }, { "contactId": "2", "personId": "4183886135", "linkedinUrl": "https://www.linkedin.com/in/carolinaportela/" } ], "metadata": { "revealEmails": true, "revealPhones": true, "signals": [ "promotion", "companyChange" ], "signalsStartDate": "2025-03-01", "partialProfile": true } } } } } } }, "responses": { "200": { "description": "The list of enriched contacts with their company details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPersonResponse" }, "example": { "contacts": { "1": { "error": null, "isCreditCharged": false, "data": { "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "companyId": 1586, "contactTags": [], "emails": [ "john.doe@amazon.com", "johndoe@gmail.com" ], "emailAddresses": [ { "email": "john.doe@amazon.com", "emailType": "work", "updateDate": "2025-11-17", "emailConfidence": "A+" }, { "email": "johndoe@gmail.com", "emailType": "private", "updateDate": "2025-11-17", "emailConfidence": "A+" } ], "phones": [ "+1 555-123-4567" ], "phoneNumbers": [ { "number": "+1 555-123-4567", "phoneType": "direct", "doNotCall": false, "updateDate": "2025-11-17" } ], "personId": 1312840528, "location": { "country": "United States", "country_iso2": "US", "continent": "North America", "is_eu_contact": false, "state": "Massachusetts", "state_code": "MA", "city": "Boston", "city_id": 4930956, "location_coordinates": [ -71.05976867675781, 42.358428955078125 ] }, "jobTitle": { "title": "Engineering Manager", "departments": [ "Engineering & Technical" ], "seniority": "Manager" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/johndoe", "xUrl": "https://twitter.com/johndoe" }, "jobStartDate": "2022-03-01", "previousJob": { "company": { "name": "TechCorp", "domain": "techcorp.com" }, "jobTitle": { "title": "Senior Software Engineer", "departments": [ "Engineering & Technical" ] } }, "updateDate": "2025-11-17", "linkedinFollowersCount": 2800, "linkedinConnectionsCount": 450, "linkedinCertifications": [ { "companyName": "AWS", "title": "AWS Certified Solutions Architect", "dateYear": 2023, "dateMonth": 8 } ], "linkedinCourses": [ { "school": { "name": "MIT" }, "degree": "Master of Engineering", "startDateYear": 2018, "endDateYear": 2020 } ], "linkedinAwards": [ { "title": "Engineering Excellence Award", "companyName": "TechCorp", "dateYear": 2021, "dateMonth": 12 } ], "linkedinSkills": [ "Cloud Architecture", "Team Leadership", "System Design" ] } }, "2": { "error": null, "isCreditCharged": false, "data": { "firstName": "Jane", "lastName": "Smith", "fullName": "Jane Smith", "companyId": 33222678, "contactTags": [], "emails": [ "jane.smith@lusha.com" ], "emailAddresses": [ { "email": "jane.smith@lusha.com", "emailType": "work", "updateDate": "2025-11-18", "emailConfidence": "A+" } ], "phones": [], "phoneNumbers": [], "personId": 3965070011, "location": { "country": "United States", "country_iso2": "US", "continent": "North America", "is_eu_contact": false }, "jobTitle": { "title": "Solutions Engineer", "departments": [ "Engineering & Technical" ], "seniority": "Non-Manager" }, "socialLinks": { "linkedin": "https://www.linkedin.com/in/janesmith", "xUrl": "https://twitter.com/janesmith" }, "jobStartDate": "2022-10-17", "previousJob": { "company": {}, "jobTitle": {} }, "updateDate": "2025-11-18", "linkedinFollowersCount": 2800, "linkedinConnectionsCount": 450, "linkedinCertifications": [ { "companyName": "AWS", "title": "AWS Certified Solutions Architect", "dateYear": 2023, "dateMonth": 8 } ], "linkedinCourses": [ { "school": { "name": "MIT" }, "degree": "Master of Engineering", "startDateYear": 2018, "endDateYear": 2020 } ], "linkedinAwards": [ { "title": "Engineering Excellence Award", "companyName": "TechCorp", "dateYear": 2021, "dateMonth": 12 } ], "linkedinSkills": [ "Cloud Architecture", "Team Leadership", "System Design" ] } } }, "companies": { "1586": { "name": "Amazon", "description": "Amazon is guided by four principles: customer obsession rather than competitor focus, passion for invention, commitment to operational excellence, and long-term thinking. We are driven by the excitement of building technologies, inventing products, and providing services that change lives. We embrace new ways of doing things, make decisions quickly, and are not afraid to fail. We have the scope and capabilities of a large company, and the spirit and heart of a small one.\n\nTogether, Amazonians research and develop new technologies from Amazon Web Services to Alexa on behalf of our customers: shoppers, sellers, content creators, and developers around the world.\n\nOur mission is to be Earth's most customer-centric company. Our actions, goals, projects, programs, and inventions begin and end with the customer top of mind.\n\nYou'll also hear us say that at Amazon, it's always \"Day 1.\" What do we mean? That our approach remains the same as it was on Amazon's very first day - to make smart, fast decisions, stay nimble, invent, and focus on delighting our customers.", "domains": { "homepage": "amazon.com", "email": "amazon.com" }, "homepageUrl": "https://amazon.com", "fqdn": "www.amazon.com", "location": { "city": "Seattle", "continent": "North America", "country": "United States", "rawLocation": "2127 7th Ave.; Seattle, WA 98109, US", "countryIso2": "US", "state": "Washington", "stateCode": "WA", "locationCoordinates": [ -122.33206939697266, 47.60620880126953 ] }, "companySize": [ 100001, 10000000 ], "revenueRange": [ 1000000000, 10000000000 ], "logoUrl": "https://logo.lusha.co/amazon-logo.jpg", "social": { "linkedin": "https://www.linkedin.com/company/amazon", "crunchbase": "https://www.crunchbase.com/organization/amazon" }, "specialities": [ "ecommerce", "internet of things platform", "operations", "retail" ], "technologies": null, "funding": null, "intent": { "detectedTopics": [ { "topicName": "Model Based Systems Engineering (MBSE)", "metadata": { "topicScore": 82, "topicTrend": "-4" } } ], "topicCount": 1 }, "mainIndustry": "Technology, Information & Media", "subIndustry": "E-Commerce & Marketplace", "industryPrimaryGroupDetails": { "sics": [ { "sic": 5961, "description": "Catalog and mail-order houses" } ] } }, "33222678": { "name": "Lusha", "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.\n\nLusha's Sales Streaming Platform is built around Sales Playlists that continuously fill up with their ideal prospects – think \"Spotify for sales.\" With AI doing the heavy lifting, Lusha uncovers great-fit leads salespeople never knew existed and executes tailored, perfectly timed cadences that get meetings booked. And the more you use Lusha, the smarter it gets.\n\nWith Sales Streaming, salespeople spend most of their time face-to-face with relevant prospects, driving 4-6X more business.", "domains": { "homepage": "lusha.com", "email": "lusha.com" }, "homepageUrl": "https://lusha.com", "fqdn": "www.lusha.com", "location": { "city": "Boston", "continent": "North America", "country": "United States", "rawLocation": "800 Boylston St; Suite 1410; Boston, Massachusetts 02199, US", "countryIso2": "US", "state": "Massachusetts", "stateCode": "MA", "locationCoordinates": [ -71.05976867675781, 42.358428955078125 ] }, "companySize": [ 201, 500 ], "revenueRange": [], "logoUrl": "https://logo.lusha.co/lusha-logo.jpg", "social": { "linkedin": "https://www.linkedin.com/company/lushadata", "crunchbase": "https://www.crunchbase.com/organization/lusha" }, "specialities": [ "data accuracy", "data availability", "data enrichment", "inside sales", "lead capture", "lead gen", "lead generation", "lead generation software", "lead intelligence", "lead mining", "lead nurturing", "prospecting", "sales enablement", "sales intelligence" ], "technologies": null, "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" }, "intent": { "detectedTopics": [ { "topicName": "HIPAA Compliance", "metadata": { "topicScore": 78, "topicTrend": "-3" } }, { "topicName": "Software Development Lifecycle", "metadata": { "topicScore": 74, "topicTrend": "-1" } }, { "topicName": "Asana", "metadata": { "topicScore": 72, "topicTrend": "New" } }, { "topicName": "Agile Transformation", "metadata": { "topicScore": 71, "topicTrend": "+7" } }, { "topicName": "Rally Software", "metadata": { "topicScore": 70, "topicTrend": "+8" } }, { "topicName": "VersionOne", "metadata": { "topicScore": 70, "topicTrend": "-10" } } ], "topicCount": 6 }, "mainIndustry": "Technology, Information & Media", "subIndustry": "Software Development", "industryPrimaryGroupDetails": { "sics": [ { "sic": 7371, "description": "Custom computer programming services" } ], "naics": [ { "naics": 541511, "description": "Custom Computer Programming Services" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/company": { "get": { "tags": [ "Enrichment" ], "summary": "Search Single Company", "description": "Find detailed information about a single company by using different paramaters.\n>##### Endpoint:\n ```\nGET https://api.lusha.com/v2/company\n ```\n\n>##### Notes: \n - At least one of `domain`, `company`, or `companyId` is required.\n - Signal sub-filters (`newsEventTypes`, `hiringByDepartments`, `hiringByLocations`) are not supported on this endpoint. Use `POST /bulk/company/v2` with the `signalsFilters` parameter for filtered signal retrieval.\n", "operationId": "searchSingleCompanyV2", "parameters": [ { "name": "domain", "in": "query", "description": "The domain name associated with the company", "schema": { "type": "string" }, "example": "example.com" }, { "name": "company", "in": "query", "description": "The name of the company", "schema": { "type": "string" }, "example": "Lusha" }, { "name": "companyId", "in": "query", "description": "A unique identifier for a Lusha company.\n", "schema": { "type": "string" }, "example": "1234567890" }, { "name": "signals", "in": "query", "description": "Array of signal types to retrieve for the company.\n- `allSignals`: All available signal types\n\n> See [Signal Filters](https://docs.lusha.com/apis/openapi/signal-filters/getsignaloptions) for complete list of available signals and their categories\n", "schema": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": [ "itSpendIncrease" ] } }, { "name": "signalsStartDate", "in": "query", "description": "Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.\n", "schema": { "type": "string", "format": "date", "example": "2025-03-01" } }, { "name": "partialCompany", "in": "query", "description": "Expand coverage with partial company profiles\n", "schema": { "type": "boolean", "default": true, "example": false } } ], "responses": { "200": { "description": "Company information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Enrichment" ], "summary": "Search Multiple Companies", "description": "Search for multiple companies in a single request. Provide a list of companies with \nidentifiers like domain names or company IDs.\n>##### Endpoint:\n ```\nPOST https://api.lusha.com/bulk/company/v2\n ```\n\n\n>##### Notes: \n - At least one of `domain`, `company`, or `companyId` is required. \n - You can process up to 100 companies per request.\n", "operationId": "searchMultipleCompaniesV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesBulkRequest" }, "example": { "companies": [ { "id": "1", "name": "Lusha" }, { "id": "2", "domain": "google.com" } ] } } } }, "responses": { "200": { "description": "Bulk company search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesBulkResponse" }, "example": { "1": { "id": 33222678, "lushaCompanyId": "16303253", "name": "Lusha", "companySize": [ 201, 500 ], "fqdn": "www.lusha.com", "founded": "2016", "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.\n\nLusha's Sales Streaming Platform is built around Sales Playlists that continuously fill up with their ideal prospects – think \"Spotify for sales.\" With AI doing the heavy lifting, Lusha uncovers great-fit leads salespeople never knew existed and executes tailored, perfectly timed cadences that get meetings booked. And the more you use Lusha, the smarter it gets.\n\nWith Sales Streaming, salespeople spend most of their time face-to-face with relevant prospects, driving 4-6X more business.", "logoUrl": "https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg", "industryPrimaryGroupDetails": { "sics": [ { "sic": 7371, "description": "Custom computer programming services" } ], "naics": [ { "naics": 541511, "description": "Custom Computer Programming Services" } ] }, "linkedin": "https://www.linkedin.com/company/lushadata", "mainIndustry": "Technology, Information & Media", "subIndustry": "Software Development", "city": "Boston", "state": "Massachusetts", "country": "United States", "countryIso2": "US", "continent": "North America", "rawLocation": "800 Boylston St; Suite 1410; Boston, Massachusetts 02199, US", "linkedinFollowers": 1950, "emailDomain": "lusha.com", "alternativeName": "lusha systems", "companyType": "Private company", "lushaPopularityTier": 2, "employeesInLinkedin": 320, "companyLocations": [ { "city": "Boston", "continent": "North America", "country": "United States", "country_iso2": "US", "location_coordinates": [ -71.05976867675781, 42.358428955078125 ], "state": "Massachusetts", "state_code": "MA" }, { "city": "Tel Aviv", "continent": "Asia", "country": "Israel", "country_iso2": "IL", "location_coordinates": [ 34.781769, 32.0853 ], "state": null, "state_code": null } ], "crunchbase": "https://www.crunchbase.com/organization/lusha", "specialities": [ "data accuracy", "data availability", "data enrichment", "inside sales", "lead capture", "lead gen", "lead generation", "lead generation software", "lead intelligence", "lead mining", "lead nurturing", "prospecting", "sales enablement", "sales intelligence" ], "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" }, "intent": { "detectedTopics": [ { "topicName": "HIPAA Compliance", "metadata": { "topicScore": 78, "topicTrend": "-3" } }, { "topicName": "Software Development Lifecycle", "metadata": { "topicScore": 74, "topicTrend": "-1" } }, { "topicName": "Asana", "metadata": { "topicScore": 72, "topicTrend": "New" } }, { "topicName": "Agile Transformation", "metadata": { "topicScore": 71, "topicTrend": "+7" } }, { "topicName": "Rally Software", "metadata": { "topicScore": 70, "topicTrend": "+8" } }, { "topicName": "VersionOne", "metadata": { "topicScore": 70, "topicTrend": "-10" } } ], "topicCount": 6 } }, "2": { "id": 1441, "lushaCompanyId": "10117615", "name": "Google", "companySize": [ 100001, 10000000 ], "revenueRange": [ 1000000000, 10000000000 ], "fqdn": "www.google.com", "description": "A problem isn't truly solved until it's solved for all. Googlers build products that help create opportunities for everyone, whether down the street or across the globe. Bring your insight, imagination and a healthy disregard for the impossible. Bring everything that makes you unique. Together, we can build for everyone.\n\nCheck out our career opportunities at goo.gle/3DLEokh", "logoUrl": "https://logo.lusha.co/coresignal/202405/c/82/c822c1b63853ed273b89687ac505f9fa", "industryPrimaryGroupDetails": { "sics": [ { "sic": 7372, "description": "Prepackaged software" } ], "naics": [ { "naics": 513210, "description": "Software Publishers" } ] }, "linkedin": "https://www.linkedin.com/company/google", "mainIndustry": "Technology, Information & Media", "subIndustry": "Software Development", "city": "Mountain View", "state": "California", "country": "United States", "countryIso2": "US", "continent": "North America", "rawLocation": "1600 Amphitheatre Parkway; Mountain View, CA 94043, US", "linkedinFollowers": 23500000, "emailDomain": "google.com", "alternativeName": "google llc", "companyType": "Public company", "lushaPopularityTier": 1, "employeesInLinkedin": 182000, "companyLocations": [ { "city": "Mountain View", "continent": "North America", "country": "United States", "country_iso2": "US", "location_coordinates": [ -122.08415985107422, 37.4219970703125 ], "state": "California", "state_code": "CA" }, { "city": "New York", "continent": "North America", "country": "United States", "country_iso2": "US", "location_coordinates": [ -74.00597381591797, 40.71272277832031 ], "state": "New York", "state_code": "NY" } ], "crunchbase": "https://www.crunchbase.com/organization/g-pay", "specialities": [ "ads", "android", "apps", "artificial intelligence agents", "cloud", "hardware", "machine learning", "mobile", "online video", "search", "software", "virtual reality", "youtube channel" ], "intent": { "detectedTopics": [ { "topicName": "Rally Software", "metadata": { "topicScore": 70, "topicTrend": "-6" } }, { "topicName": "Deel, Inc.", "metadata": { "topicScore": 70, "topicTrend": "-8" } }, { "topicName": "GitHub Enterprise", "metadata": { "topicScore": 70, "topicTrend": "-3" } } ], "topicCount": 3 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/prospecting/filters/contacts/departments": { "get": { "tags": [ "Contact Filters" ], "summary": "Departments", "description": "Get list of available departments for contact filtering", "operationId": "getContactDepartments", "responses": { "200": { "description": "List of departments", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Business Development", "Consulting", "Engineering", "Marketing" ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/contacts/seniority": { "get": { "tags": [ "Contact Filters" ], "summary": "Seniority", "description": "Get list of available seniority levels for contact filtering", "operationId": "getContactSeniority", "responses": { "200": { "description": "List of seniority levels", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ { "id": 10, "name": "founder" }, { "id": 9, "name": "c-suite" }, { "id": 8, "name": "vice president" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/contacts/existing_data_points": { "get": { "tags": [ "Contact Filters" ], "summary": "Data Points", "description": "Get list of available data points for contact filtering", "operationId": "getContactDataPoints", "responses": { "200": { "description": "List of data points", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "phone", "work_email", "mobile_phone", "direct_phone" ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/contacts/all_countries": { "get": { "tags": [ "Contact Filters" ], "summary": "Countries", "description": "Get list of all available countries for contact filtering", "operationId": "getContactCountries", "responses": { "200": { "description": "List of countries with codes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryFilter" } }, "example": [ { "name": "United States", "code": "US" }, { "name": "United Kingdom", "code": "GB" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/contacts/locations": { "post": { "tags": [ "Contact Filters" ], "summary": "Locations", "description": "Search for locations by text for contact filtering", "operationId": "searchContactLocations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationSearchRequest" }, "example": { "text": "un" } } } }, "responses": { "200": { "description": "Matching locations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LocationFilter" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/names": { "post": { "tags": [ "Company Filters" ], "summary": "Names", "description": "Search for company names by text", "operationId": "searchCompanyNames", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyNameSearchRequest" }, "example": { "text": "lusha" } } } }, "responses": { "200": { "description": "Matching companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyNameResult" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/industries_labels": { "get": { "tags": [ "Company Filters" ], "summary": "Industries", "description": "Get list of available industries for company filtering", "operationId": "getCompanyIndustries", "responses": { "200": { "description": "Industry hierarchy", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IndustryLabel" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/sizes": { "get": { "tags": [ "Company Filters" ], "summary": "Sizes", "description": "Get list of available company size ranges", "operationId": "getCompanySizes", "responses": { "200": { "description": "Company size ranges", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySizeRange" } }, "example": [ { "min": 1, "max": 10 }, { "min": 11, "max": 50 }, { "min": 51, "max": 200 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/revenues": { "get": { "tags": [ "Company Filters" ], "summary": "Revenues", "description": "Get list of available revenue ranges", "operationId": "getCompanyRevenues", "responses": { "200": { "description": "Revenue ranges", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueRange" } }, "example": [ { "min": 1, "max": 1000000 }, { "min": 1000001, "max": 10000000 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/locations": { "post": { "tags": [ "Company Filters" ], "summary": "Locations", "description": "Search for company locations by text", "operationId": "searchCompanyLocations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationSearchRequest" }, "example": { "text": "Israel" } } } }, "responses": { "200": { "description": "Matching locations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyLocationFilter" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/sics": { "get": { "tags": [ "Company Filters" ], "summary": "SIC Codes", "description": "Get list of available SIC codes", "operationId": "getCompanySicCodes", "responses": { "200": { "description": "SIC codes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SicCode" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/naics": { "get": { "tags": [ "Company Filters" ], "summary": "NAICS Codes", "description": "Get list of available NAICS codes", "operationId": "getCompanyNaicsCodes", "responses": { "200": { "description": "NAICS codes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NaicsCode" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/intent_topics": { "get": { "tags": [ "Company Filters" ], "summary": "Intent Topics", "description": "Get list of available intent topics", "operationId": "getCompanyIntentTopics", "responses": { "200": { "description": "Intent topics", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Android", "Accounting", "Zero Trust", "Digital Sales" ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/filters/companies/technologies": { "post": { "tags": [ "Company Filters" ], "summary": "Technologies", "description": "Search for technologies by text", "operationId": "searchCompanyTechnologies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TechnologySearchRequest" }, "example": { "text": "rss" } } } }, "responses": { "200": { "description": "Matching technologies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Technology" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/prospecting/contact/search": { "post": { "tags": [ "Prospecting - Search & Enrich" ], "summary": "Search Contacts", "description": "Search for contacts using various filters. This is step 2 of the prospecting process.\n\n*Endpoint*: **(POST) https://api.lusha.com/prospecting/contact/search**\n---\n##### Signal Filtering (Premium Feature)\nFilter contacts by signal types to find prospects at key career moments.\n\n > **Note:** This is a premium feature. Credits are charged for each signal type that returns results.\n\n---\n##### DNC Filtering (Scale Feature)\nUse `excludeDnc: true` at the top level of the request body to filter out contacts whose phone numbers are all marked Do Not Call.\n- Contacts with **at least one callable phone** appear in results - Only callable phones are shown — DNC phones are hidden - Contacts with **only DNC phones** are excluded entirely\n> **Note**: Returns **403** on unsupported plans.\n", "operationId": "searchProspectingContacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearchRequest" }, "examples": { "basicContactSearch": { "summary": "Basic contact search with filters", "value": { "pages": { "page": 0, "size": 20 }, "filters": { "contacts": { "include": { "departments": [ "Engineering & Technical", "Marketing" ], "seniority": [ 4, 5 ], "existing_data_points": [ "phone", "work_email", "mobile_phone" ], "locations": [ { "continent": "North America", "country": "United States", "city": "New York", "state": "New York", "country_grouping": "na" } ], "signals": { "names": [ "allSignals", "promotion", "companyChange" ], "startDate": "2025-11-01" } }, "exclude": { "departments": [ "Human Resources" ] } }, "companies": { "include": { "names": [ "Apple", "Microsoft" ], "locations": [ { "country": "United States" } ], "technologies": [ "Salesforce", "Amazon Web Services" ], "mainIndustriesIds": [ 4, 5 ], "subIndustriesIds": [ 101 ], "intentTopics": [ "Digital Sales" ], "sizes": [ { "min": 100, "max": 1000 } ], "revenues": [ { "min": 10000000, "max": 100000000 } ], "sicCodes": [ "1011", "1021" ], "naicsCodes": [ "11", "21" ] }, "exclude": {} } } } }, "simpleExample": { "summary": "Simple search example", "value": { "pages": { "page": 0, "size": 10 }, "filters": { "contacts": { "include": { "departments": [ "Sales" ] } } } } }, "withSearchText": { "summary": "Contact search with searchText filter", "value": { "pages": { "page": 0, "size": 50 }, "filters": { "contacts": { "include": { "searchText": "Amit", "departments": [ "Engineering & Technical" ] }, "exclude": { "searchText": "Ronen" } }, "companies": { "include": { "searchText": "finance marketing in Germany DE" } } } } }, "dncFilterExample": { "summary": "Exclude DNC contacts — Scale only (LD-2313)", "value": { "pages": { "page": 0, "size": 20 }, "excludeDnc": true, "filters": { "contacts": { "include": { "linkedinUrls": [ "https://www.linkedin.com/in/justin-pernitz", "https://www.linkedin.com/in/andrewbarrettbettcher", "https://www.linkedin.com/in/aitor-moreno-artola-11a2a985" ] } }, "companies": {} } } }, "employeesInLinkedInContactExample": { "summary": "Filter contacts by company LinkedIn employee count (staging only)", "value": { "pages": { "page": 0, "size": 20 }, "filters": { "contacts": { "include": { "departments": [ "Sales" ] } }, "companies": { "include": { "employeesInLinkedIn": { "min": 500 } } } } } } } } } }, "responses": { "200": { "description": "Search results with contact IDs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden — DNC filter not available on your current plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 403, "message": "Exclude DNC is not supported on your current plan. Please contact support or your account manager for assistance." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/prospecting/contact/enrich": { "post": { "tags": [ "Prospecting - Search & Enrich" ], "summary": "Enrich Contacts", "description": "Enrich contacts from search results. This is step 3 of the prospecting process.\n\n *Endpoint*: **(POST) https://api.lusha.com/prospecting/contact/enrich** \n---\n\n⚠️ **Important Notice - Unified Credits Plan Required**\n\n| Parameter | Requirement |\n|-----------|-------------|\n| `revealEmails` and `revealPhones` | Only available to customers on the **Unified Credits** pricing plan |\n| Plan Restriction | Attempting to use these parameters on other plans will result in a **403 Unauthorized** error |\n| Default Behavior | When neither parameter is used, the API returns **both email addresses and phone numbers**, if available |\n\n---\n", "operationId": "enrichProspectingContacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnrichRequest" }, "examples": { "basicExample": { "summary": "Basic enrichment request", "value": { "requestId": "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7", "contactIds": [ "37b4c536-eaec-11ef-ad4b-a75f8e9e1484" ] } }, "unifiedCreditsExample": { "summary": "Unified Credits plan with selective reveal", "value": { "requestId": "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7", "contactIds": [ "ddfb6966-741f-4fca-a62b-e553d4ac12f8" ], "revealEmails": false, "revealPhones": true } } } } } }, "responses": { "200": { "description": "Enriched contact data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnrichResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/prospecting/company/search": { "post": { "tags": [ "Prospecting - Search & Enrich" ], "summary": "Search Companies", "description": "Search for companies using various filters. This is step 2 of the prospecting process.\n\n*Endpoint*: **(POST) https://api.lusha.com/prospecting/company/search**\n---\n\n##### Signal Filtering (Premium Feature)\nFilter companies by signal types to identify those with recent business events and changes.\n\n > **Note:** This is a premium feature. Credits are charged for each signal type that returns results.\n", "operationId": "searchProspectingCompanies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequest" }, "examples": { "companyLocationsExample": { "summary": "Filter by site-level office locations (staging only)", "value": { "pages": { "page": 0, "size": 20 }, "filters": { "companies": { "include": { "companyLocations": [ { "country": "United States", "state": "California" }, { "country": "Germany" } ] } } } } }, "employeesInLinkedInExample": { "summary": "Filter by LinkedIn employee count range (staging only)", "value": { "pages": { "page": 0, "size": 20 }, "filters": { "companies": { "include": { "employeesInLinkedIn": { "min": 100, "max": 5000 } } } } } } } } } }, "responses": { "200": { "description": "Search results with company IDs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/prospecting/company/enrich": { "post": { "tags": [ "Prospecting - Search & Enrich" ], "summary": "Enrich Companies", "description": "Enrich companies from search results. This is step 3 of the prospecting process.\n\n *Endpoint*: **(POST) https://api.lusha.com/prospecting/company/enrich**\n", "operationId": "enrichProspectingCompanies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEnrichRequest" } } } }, "responses": { "200": { "description": "Enriched company data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEnrichResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/signals/filters/{objectType}": { "get": { "tags": [ "Signals" ], "summary": "Get Signal Options", "description": "Retrieve available signal options for a specific entity type (contact or company).\nThis endpoint returns the list of signal types you can filter by when enriching contacts or companies. \n\n\n **Endpoints:**\n\n * **Contacts:** `GET /api/signals/filters/contact`\n * **Companies:** `GET /api/signals/filters/company`\n\n\n ### Available Signal Types\n\n \n #### For contacts:\n\n * **`allSignals`** - All available contact signal types\n * **`promotion`** - Job title promotions \n * **`companyChange`** - Company changes\n \n ---\n \n #### For companies:\n\n * **`allSignals`** - All available company signal types\n \n
\n \n **Hiring & Workforce:**\n \n * **`surgeInHiring`** - Overall hiring activity increase\n * **`surgeInHiringByDepartment`** - Department-specific hiring surges\n * **`surgeInHiringByLocation`** - Location-specific hiring surges\n \n
\n \n **Headcount Trends:**\n \n | Signal | Description |\n |--------|-------------|\n | `headcountIncrease1m` / `headcountDecrease1m` | 1-month employee count changes |\n | `headcountIncrease3m` / `headcountDecrease3m` | 3-month employee count changes |\n | `headcountIncrease6m` / `headcountDecrease6m` | 6-month employee count changes |\n | `headcountIncrease12m` / `headcountDecrease12m` | 12-month employee count changes |\n \n
\n \n **Technology & Digital Presence:**\n \n * **`websiteTrafficIncrease`** - Website traffic growth\n * **`websiteTrafficDecrease`** - Website traffic decline\n * **`itSpendIncrease`** - IT spending increase\n * **`itSpendDecrease`** - IT spending decrease\n \n **News Events:**\n\n To retrieve company news, use one or more of the following category values:\n\n\n | Signal | Included Events |\n |--------|-----------------|\n | `commercialActivityNews` | Partnership, New Customer, New Vendor |\n | `corporateStrategyNews` | M&A, Facilities Expansion, New Location, Facility Closure, Asset Sale, Lawsuit Filed |\n | `financialEventsNews` | Funding Round, Asset Investment, Strategic Investment, IPO |\n | `marketIntelligenceNews` | Event Participation, Recognition, Competitor Activity |\n | `peopleNews` | Executive Hire, Executive Departure, Executive Promotion, Headcount Increase, Headcount Decrease |\n | `productActivityNews` | Product Launch, Product Development, Product Integration |\n | `riskNews` | Security Issue, Lawsuit Faced |\n\n\n > The response also includes available values for signal sub-filters:\n\n * `newsEventTypes` — available event type values for news signal filtering\n * `hiringByDepartments` — available department values for hiring surge filtering\n * `hiringByLocations` — available location values for hiring surge filtering (array of `{ country, state }` objects)\n", "operationId": "getSignalOptions", "parameters": [ { "name": "objectType", "in": "path", "required": true, "description": "The type of object to get signal options for", "schema": { "type": "string", "enum": [ "contact", "company" ] }, "example": "contact" } ], "responses": { "200": { "description": "List of available signal types for the specified object type", "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "string" }, "example": [ "promotion", "companyChange" ] }, "objectType": { "type": "string", "example": "contact" }, "filterOptions": { "type": "object", "description": "Available enum values for signal sub-filters. Only present in the `company` response.", "properties": { "newsEventTypes": { "type": "array", "items": { "type": "string" }, "description": "Available values for the `newsEventTypes` filter" }, "hiringByDepartments": { "type": "array", "items": { "type": "string" }, "description": "Available values for the `hiringByDepartments` filter" } } } } }, "examples": { "contactSignals": { "summary": "Contact signal options", "value": { "signals": [ "promotion", "companyChange", "allSignals" ], "objectType": "contact" } }, "companySignals": { "summary": "Company signal options", "value": { "signals": [ "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ], "objectType": "company", "filterOptions": { "newsEventTypes": [ "Asset Investment", "Asset Sale", "Competitor Activity", "Event Participation", "Executive Departure", "Executive Hire", "Executive Promotion", "Facilities Expansion", "Facility Closure", "Funding Round", "Headcount Decrease", "Headcount Increase", "IPO", "Lawsuit Faced", "Lawsuit Filed", "M&A", "New Customer", "New Location", "New Vendor", "Partnership", "Product Development", "Product Integration", "Product Launch", "Recognition", "Security Issue", "Strategic Investment" ], "hiringByDepartments": [ "Business Development", "Consulting", "Customer Service", "Engineering & Technical", "Finance", "General Management", "Health Care & Medical", "Human Resources", "Information Technology", "Legal", "Marketing", "Operations", "Other", "Product", "Research & Analytics", "Sales" ] } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Signals API not supported on your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/signals/contacts": { "post": { "tags": [ "Signals" ], "summary": "Get Contact Signals by IDs", "description": "Retrieve signals data for a list of contact IDs.\nThis endpoint allows you to get recent activities and signals for up to 100 contacts per request.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/signals/contacts**\n\n**Default Behavior:**\n- Returns signals from the last 6 months by default\n- Use `startDate` to customize the timeframe\n- Each signal type requested counts towards credit usage\n", "operationId": "getContactSignalsById", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSignalsByIdRequest" }, "examples": { "basicExample": { "summary": "Basic request", "value": { "contactIds": [ 115889 ], "signals": [ "promotion", "companyChange" ], "startDate": "2025-01-01", "maxResultsPerSignal": 5 } }, "allSignals": { "summary": "Request all signal types", "value": { "contactIds": [ 115889 ], "signals": [ "allSignals" ], "maxResultsPerSignal": 10 } } } } } }, "responses": { "200": { "description": "Contact signals retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSignalsByIdResponse" }, "example": { "contacts": { "115889": { "personId": "115889", "companyChange": [ { "personId": "115889", "currentCompanyId": 8217, "currentCompanyName": "Callaway Golf", "currentDepartments": "R&D", "currentSeniorityLabel": "c-suite", "currentTitle": "Senior Manager, IT Solutions", "signalDate": "2025-05-01", "previousCompanyName": "Previous Corp", "previousDomain": "nextgen.com", "currentDomain": "vendavo.com" } ], "promotion": [ { "personId": "115889", "currentCompanyId": 8217, "currentCompanyName": "Callaway Golf", "currentDepartments": "R&D", "currentSeniorityLabel": "c-suite", "currentTitle": "Senior Manager, IT Solutions", "signalDate": "2025-05-01", "previousCompanyName": "Previous Corp", "previousDomain": "nextgen.com", "currentDomain": "vendavo.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 2 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/signals/contacts/search": { "post": { "tags": [ "Signals" ], "summary": "Search Contact Signals", "description": "Search for contact signals using identifiers like LinkedIn URL, email, or name + company.\nThis endpoint combines search and signal enrichment in a single request.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/signals/contacts/search**\n\n**Search Requirements:**\nEach contact can be identified by:\n- Contact ID\n- LinkedIn URL\n- Email address\n- Full name + Company (name or domain)\n\n**Default Behavior:**\n- Returns signals from the last 6 months by default\n- Contacts are matched based on provided identifiers\n- Returns both contact data and associated signals\n", "operationId": "searchContactSignals", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSignalsSearchRequest" }, "examples": { "searchByLinkedIn": { "summary": "Search by LinkedIn URL (id required)", "value": { "contacts": [ { "id": "123321", "social_link": "https://www.linkedin.com/in/ron-nabet" } ], "signals": [ "promotion", "companyChange" ], "startDate": "2025-01-01", "maxResultsPerSignal": 5 } }, "searchByEmail": { "summary": "Search by email (id required)", "value": { "contacts": [ { "id": "456654", "email": "dustin@lusha.com" } ], "signals": [ "allSignals" ], "maxResultsPerSignal": 10 } }, "searchByNameAndCompany": { "summary": "Search by name and company (id required)", "value": { "contacts": [ { "id": "987789", "full_name": "Ron Nabet", "companies": [ { "name": "Lusha" } ], "domain": "lusha.com", "is_current": true } ], "signals": [ "promotion" ], "maxResultsPerSignal": 10 } } } } } }, "responses": { "200": { "description": "Contact signals search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSignalsSearchResponse" }, "examples": { "success": { "summary": "Contact signals found via search", "value": { "contacts": { "123321": { "personId": "115889", "companyChange": [ { "personId": "115889", "currentCompanyId": 8217, "currentCompanyName": "Callaway Golf", "currentDepartments": "R&D", "currentSeniorityLabel": "c-suite", "currentTitle": "Senior Manager, IT Solutions", "signalDate": "2025-05-01", "previousCompanyName": "Previous Corp", "previousDomain": "nextgen.com", "currentDomain": "vendavo.com" } ], "promotion": [ { "personId": "115889", "currentCompanyId": 8217, "currentCompanyName": "Callaway Golf", "currentDepartments": "R&D", "currentSeniorityLabel": "c-suite", "currentTitle": "Senior Manager, IT Solutions", "signalDate": "2025-05-01", "previousCompanyName": "Previous Corp", "previousDomain": "nextgen.com", "currentDomain": "vendavo.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 2 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/signals/companies": { "post": { "tags": [ "Signals" ], "summary": "Get Company Signals by IDs", "description": "Retrieve signals data for a list of company IDs.\nThis endpoint allows you to get recent activities and signals for up to 100 companies per request.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/signals/companies**\n\n**Default Behavior:**\n- Returns signals from the last 6 months by default\n- Use `startDate` to customize the timeframe\n", "operationId": "getCompanySignalsById", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySignalsByIdRequest" }, "examples": { "basicExample": { "summary": "Basic request", "value": { "companyIds": [ 3416 ], "signals": [ "websiteTrafficIncrease" ], "startDate": "2025-01-01", "maxResultsPerSignal": 10 } }, "allSignals": { "summary": "Request all signals", "value": { "companyIds": [ 3416, 3417 ], "signals": [ "allSignals" ], "maxResultsPerSignal": 10 } } } } } }, "responses": { "200": { "description": "Company signals retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySignalsByIdResponse" }, "examples": { "multipleSignals": { "summary": "Company signals with multiple signal types", "value": { "companies": { "3416": { "companyId": "3416", "companyName": "Test", "domain": "test.com", "commercialActivityNews": [ { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "signalId": "1503910", "eventType": "partnership", "eventSummary": "Lusha announced a strategic partnership with Salesforce.", "articlePublishedDate": "2025-06-15", "articleTitle": "Lusha Partners with Salesforce", "articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.", "eventEffectiveDate": "2025-06-10", "articleUrl": "https://example.com/lusha-salesforce-partnership" } ], "websiteTrafficIncrease": [ { "companyId": "3416", "signalId": "1503902", "signalDate": "2025-06-15", "historicalAvg": 50000, "lastMonthVisits": 75000, "changeRatePercent": 50, "companyName": "Test", "domain": "test.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 2 } }, "surgeInHiringExample": { "summary": "Overall hiring surge signal", "value": { "companies": { "3416": { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "surgeInHiring": [ { "companyId": "3416", "signalId": "1503905", "signalDate": "2025-06-15", "newJobsPostedLastWeek": 25, "historicalAvg": 10, "changeRatePercent": 150, "companyName": "Lusha", "domain": "lusha.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/signals/companies/search": { "post": { "tags": [ "Signals" ], "summary": "Search Company Signals", "description": "Search for company signals using identifiers like domain, company name, or ID.\nThis endpoint combines search and signal enrichment in a single request.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/signals/companies/search**\n\n**Search Requirements:**\nEach company must have at least one identifier:\n- Company ID (as string)\n- Company name\n- Company domain\n\n**Default Behavior:**\n- Returns signals from the last 6 months by default\n- Companies are matched based on provided identifiers\n", "operationId": "searchCompanySignals", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySignalsSearchRequest" }, "examples": { "searchByDomain": { "summary": "Search by domain (id required)", "value": { "companies": [ { "id": "12344321", "domain": "lusha.com" } ], "signals": [ "itSpendIncrease" ], "startDate": "2025-01-01", "maxResultsPerSignal": 10 } }, "searchByName": { "summary": "Search by company name (id required)", "value": { "companies": [ { "id": "123123", "name": "Lusha" } ], "signals": [ "allSignals" ], "startDate": "2025-01-01", "maxResultsPerSignal": 10 } }, "multipleCompanies": { "summary": "Search multiple companies with different identifiers (id required for each)", "value": { "companies": [ { "id": "123123", "name": "Arcmedix" }, { "id": "12344321", "domain": "lusha.com" }, { "id": "1234434421", "domain": "example.com" } ], "signals": [ "itSpendIncrease" ], "startDate": "2025-01-01", "maxResultsPerSignal": 10 } } } } } }, "responses": { "200": { "description": "Company signals search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySignalsByIdResponse" }, "examples": { "multipleSignals": { "summary": "Multiple signal types found via search", "value": { "companies": { "12344321": { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "commercialActivityNews": [ { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "signalId": "1503910", "eventType": "partnership", "eventSummary": "Lusha announced a strategic partnership with Salesforce.", "articlePublishedDate": "2025-06-15", "articleTitle": "Lusha Partners with Salesforce", "articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.", "eventEffectiveDate": "2025-06-10", "articleUrl": "https://example.com/lusha-salesforce-partnership" } ], "itSpendIncrease": [ { "companyId": "3416", "signalId": "1503903", "signalDate": "2025-06-15", "estimatedAnnualItSpend": 5000000, "changeRatePercent": 25, "companyName": "Lusha", "domain": "lusha.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 2 } }, "headcountSignal": { "summary": "Headcount increase signal", "value": { "companies": { "12344321": { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "headcountIncrease3m": [ { "companyId": "3416", "signalId": "1503904", "signalDate": "2025-06-15", "baselineEmployeesCount": 500, "newEmployeesCount": 550, "changeRatePercent": 10, "companyName": "Lusha", "domain": "lusha.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 1 } }, "hiringByDepartment": { "summary": "Department-specific hiring surge", "value": { "companies": { "12344321": { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "surgeInHiringByDepartment": [ { "signalId": "1503906", "companyId": "3416", "department": "Engineering", "signalDate": "2025-06-15", "newJobsPostedLast4Weeks": 15, "historicalAvg": 5, "changeRatePercent": 200, "companyName": "Lusha", "domain": "lusha.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 1 } } }, "surgeInHiringExample": { "summary": "Overall hiring surge signal", "value": { "companies": { "12344321": { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "surgeInHiring": [ { "companyId": "3416", "signalId": "1503905", "signalDate": "2025-06-15", "newJobsPostedLastWeek": 25, "historicalAvg": 10, "changeRatePercent": 150, "companyName": "Lusha", "domain": "lusha.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 1 }, "hiringByLocation": { "summary": "Location-specific hiring surge", "value": { "companies": { "12344321": { "companyId": "3416", "companyName": "Lusha", "domain": "lusha.com", "surgeInHiringByLocation": [ { "signalId": "1503907", "companyId": "3416", "country": "United States", "state": "California", "signalDate": "2025-06-15", "newJobsPostedLast4Weeks": 20, "historicalAvg": 8, "changeRatePercent": 150, "companyName": "Lusha", "domain": "lusha.com" } ] } }, "endDate": "2025-07-31", "startDate": "2025-01-01", "creditCharged": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/account/usage": { "get": { "tags": [ "Account Management" ], "summary": "Get Account Usage Statistics", "description": "Retrieve your current API credit usage statistics including used, remaining, and total credits.\n\n*Endpoint*: **(GET) https://api.lusha.com/account/usage**\n\n**Rate Limits**: This endpoint has a specific rate limit of 5 requests per minute.\n", "operationId": "getAccountUsageStats", "responses": { "200": { "description": "Account usage statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsageStatsResponse" }, "example": { "usage": { "bulkCredits": { "used": 150, "total": 1000, "remaining": 850 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v3/lookalike/contacts": { "post": { "tags": [ "Lookalikes" ], "summary": "Contact Lookalikes", "description": "Returns contact lookalikes based on seed contacts.\n\n*Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/contacts**\n\n\n #### How It Works\n\n\n**First Request (Start a New Run):**\n- Do not send `dedupeSessionId`\n- Server generates one and returns it in the response\n- Use returned `dedupeSessionId` for subsequent \"get more\" requests\n\n**Subsequent Requests (\"Get More\"):**\n- Send the returned `dedupeSessionId` to fetch more results without duplicates\n- Server dedupes against all contacts previously returned for the `dedupeSessionId`\n- User-provided `exclude.*` is applied on every request and combined with server-side dedupe\n- Session history retained for 30 days from last activity (sliding window)\n---\n", "operationId": "getContactLookalikes", "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/johndoe" ], "emails": [ "jane@acme.com", "bob@example.com" ], "contacts": [ { "firstName": "Alice", "lastName": "Smith", "companyDomain": "sap.com" } ], "contactIds": [ 1234, 4567 ] }, "exclude": { "emails": [ "existing@customer.com" ], "linkedinUrls": [ "https://www.linkedin.com/in/already-contacted/" ], "contactIds": [ 9999 ] }, "limit": 25 } }, "secondRequestGetMore": { "summary": "Second request (get more using dedupeSessionId)", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "seeds": { "linkedinUrls": [ "https://www.linkedin.com/in/johndoe" ], "emails": [ "jane@acme.com", "bob@example.com" ], "contacts": [ { "firstName": "Alice", "lastName": "Smith", "companyDomain": "sap.com" } ], "contactIds": [ 1234, 4567 ] }, "exclude": { "emails": [ "existing@customer.com" ], "linkedinUrls": [ "https://www.linkedin.com/in/already-contacted/" ], "contactIds": [ 9999 ] }, "limit": 25 } } } } } }, "responses": { "200": { "description": "Successfully retrieved contact lookalikes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLookalikesResponse" }, "examples": { "firstResponse": { "summary": "Example response (first request)", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "results": [ { "contactId": "9659196", "firstName": "Sarah", "lastName": "Johnson", "socialLinks": { "linkedin": "https://www.linkedin.com/in/sarahjohnson" }, "company": { "companyId": "8605368", "name": "Marriott International", "domain": "marriott.com" }, "jobTitle": { "title": "VP of Sales", "departments": [ "Sales" ], "seniority": "Director" }, "location": { "country": "United States", "state": "Maryland", "city": "Bethesda" } } ], "meta": { "returned": 1, "hasMore": true }, "creditsCharged": 3 } }, "secondResponse": { "summary": "Example response (get more)", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "results": [ { "contactId": "9659197", "firstName": "Michael", "lastName": "Davis", "socialLinks": { "linkedin": "https://www.linkedin.com/in/michaeldavis" }, "company": { "companyId": "8605369", "name": "Hilton", "domain": "hilton.com" }, "jobTitle": { "title": "Sales Director", "departments": [ "Sales" ], "seniority": "Director" }, "location": { "country": "United States", "state": "Virginia", "city": "McLean" } } ], "meta": { "returned": 1, "hasMore": true } } } } } } }, "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" }, "example": { "code": "DEDUPE_SESSION_INVALID", "message": "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run." } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v3/lookalike/companies": { "post": { "tags": [ "Lookalikes" ], "summary": "Company Lookalikes", "description": "Returns company lookalikes based on seed companies.\n\n*Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/companies**\n\n\n #### How It Works\n\n\n**First Request (Start a New Run):**\n- Do not send `dedupeSessionId`\n- Server generates one and returns it in the response\n- Use returned `dedupeSessionId` for subsequent \"get more\" requests\n\n**Subsequent Requests (\"Get More\"):**\n- Send the returned `dedupeSessionId` to fetch more results without duplicates\n- Server uses `dedupeSessionId` to deduplicate companies already returned\n- Session history retained for 30 days from last activity (sliding window)\n---\n", "operationId": "getCompanyLookalikes", "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", "the-company.com" ], "linkedinUrls": [ "https://www.linkedin.com/company/google", "https://www.linkedin.com/company/someone" ] }, "exclude": { "domains": [ "existingcustomer.com", "already-sent.com" ], "linkedinUrls": [ "https://www.linkedin.com/company/already-sent/" ] }, "limit": 100 } }, "secondRequest": { "summary": "Second request (get more using dedupeSessionId)", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "seeds": { "domains": [ "sap.com", "oracle.com", "the-company.com" ], "linkedinUrls": [ "https://www.linkedin.com/company/google", "https://www.linkedin.com/company/someone" ] }, "exclude": { "domains": [ "existingcustomer.com", "already-sent.com" ], "linkedinUrls": [ "https://www.linkedin.com/company/already-sent/" ] }, "limit": 100 } } } } } }, "responses": { "200": { "description": "Successfully retrieved company lookalikes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookalikesResponse" }, "examples": { "firstResponse": { "summary": "Example response (first request)", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "results": [ { "domain": "marriott.com", "linkedinUrl": "https://www.linkedin.com/company/marriott-international", "name": "Marriott International", "employeeCount": 255334, "industry": "Hospitality", "location": { "country": "United States", "state": "Maryland", "city": "Bethesda" } } ], "meta": { "returned": 1, "hasMore": true }, "creditsCharged": 3 } }, "secondResponse": { "summary": "Example response (get more)", "value": { "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613", "results": [ { "domain": "hilton.com", "linkedinUrl": "https://www.linkedin.com/company/hilton", "name": "Hilton", "employeeCount": 173000, "industry": "Hospitality", "location": { "country": "United States", "state": "Virginia", "city": "McLean" } } ], "meta": { "returned": 1, "hasMore": true } } } } } } }, "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" }, "example": { "statusCode": 410, "errors": [ "DEDUPE_SESSION_INVALID" ], "message": "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run." } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } }, { "index": 1, "success": true, "subscription": { "id": "507f1f77bcf86cd799439012", "entityType": "contact", "entityId": "456", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha", "name": "Contact 456", "isActive": true, "createdAt": "2026-02-02T10:00:00.000Z", "updatedAt": "2026-02-02T10:00:00.000Z" } }, { "index": 2, "success": true, "subscription": { "id": "507f1f77bcf86cd799439013", "entityType": "contact", "entityId": "789", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha", "name": "Contact 789", "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'" } }, { "index": 2, "success": true, "subscription": { "id": "507f1f77bcf86cd799439013", "entityType": "contact", "entityId": "789", "signalTypes": [ "promotion", "companyChange" ], "url": "https://example.com/webhooks/lusha", "name": "Contact 789", "isActive": true, "createdAt": "2026-02-02T10:00:00.000Z", "updatedAt": "2026-02-02T10:00:00.000Z" } } ] } } } } } }, "400": { "description": "Bad request - URL validation failed or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidInput": { "summary": "Invalid request parameters", "value": { "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" }, "examples": { "limitReached": { "summary": "Maximum subscriptions limit reached", "value": { "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**What Gets Tested:**\n- URL accessibility and response time\n- Complete delivery pipeline (for full mode)\n- Signature generation and headers\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" } }, { "index": 1, "success": true, "subscription": { "id": "sub-456", "entityType": "company", "entityId": "456", "name": "Company Webhook" } }, { "index": 2, "success": true, "subscription": { "id": "sub-789", "entityType": "contact", "entityId": "789" } } ] } }, "partialSuccess": { "summary": "Some deletions failed (partial success)", "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" } }, { "index": 2, "success": true, "subscription": { "id": "sub-789", "entityType": "contact", "entityId": "789" } } ] } } } } } }, "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" } } } } }, "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.\n\nInclude this key in the `api_key` header for all requests.\n" } }, "parameters": { "firstName": { "name": "firstName", "in": "query", "description": "The first name of the person", "schema": { "type": "string" }, "example": "Dustin" }, "lastName": { "name": "lastName", "in": "query", "description": "The last name of the person", "schema": { "type": "string" }, "example": "Moskovitz" }, "personId": { "name": "personId", "in": "query", "description": "The unique person identifier in Lusha", "schema": { "type": "string" }, "example": "4183886134" }, "companyName": { "name": "companyName", "in": "query", "description": "The name of the company the person works at", "schema": { "type": "string" }, "example": "Lusha" }, "companyDomain": { "name": "companyDomain", "in": "query", "description": "The domain name of the company", "schema": { "type": "string" }, "example": "lusha.com" }, "email": { "name": "email", "in": "query", "description": "The email address of the person", "schema": { "type": "string" }, "example": "dustin@lusha.com" }, "linkedinUrl": { "name": "linkedinUrl", "in": "query", "description": "The LinkedIn URL of the person", "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/dustin/" }, "refreshJobInfo": { "name": "refreshJobInfo", "in": "query", "description": "Set to true to refresh and update the job details for the person. \nThis ensures that outdated job information is replaced with the most recent data.\n", "schema": { "type": "boolean", "default": false }, "example": true }, "filterBy": { "name": "filterBy", "in": "query", "description": "Filters results based on specific contact details. Available options:\n- `phoneNumbers`: Only return contacts with phone numbers\n- `emailAddresses`: Only return contacts with email addresses\n\nBy default, results will include contacts with at least one contact detail.\n", "schema": { "type": "string", "enum": [ "phoneNumbers", "emailAddresses" ] } }, "revealEmails": { "name": "revealEmails", "in": "query", "description": "Set `revealEmails=true` to retrieve only the email address of the contact.\n", "schema": { "type": "boolean", "default": true }, "example": true }, "revealPhones": { "name": "revealPhones", "in": "query", "description": "Set `revealPhones=true` to retrieve only the phone number of the contact.\n", "schema": { "type": "boolean", "default": true }, "example": true }, "signals": { "name": "signals", "in": "query", "description": "Array of signal types to retrieve for the contact.\n- `allSignals`: All available signal types\n- `promotion`: Promotion signals\n- `companyChange`: Company change signals\n", "schema": { "type": "array", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] } }, "example": [ "promotion" ] }, "signalsStartDate": { "name": "signalsStartDate", "in": "query", "description": "Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.\n", "schema": { "type": "string", "format": "date" }, "example": "2025-03-01" }, "partialProfile": { "name": "partialProfile", "in": "query", "description": "Search for a single contact with the option to receive a partial profile.\n", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } }, "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" } } } }, "Forbidden": { "description": "Forbidden - account inactive or feature not available", "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" } }, "featureNotAvailable": { "summary": "Feature not available for pricing plan", "value": { "statusCode": 403, "message": "Your pricing version does not support requesting individual datapoints [revealEmails, revealPhones]" } }, "subscriptionLimitReached": { "summary": "Subscription limit reached", "value": { "statusCode": 403, "message": "Maximum subscriptions limit reached for your account" } }, "dncNotSupported": { "summary": "DNC filter not supported on current plan", "value": { "statusCode": 403, "message": "Exclude DNC is not supported on your current plan. Please contact support or your account manager for assistance." } } } } } }, "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": { "RateLimit-Limit": { "description": "The total number of allowed requests per second", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "The time (in seconds) until the rate limit quota is reset", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Daily": { "description": "The number of remaining requests for your daily quota", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Daily": { "description": "The time when your daily quota will reset", "schema": { "type": "integer" } } } }, "GDPRRestricted": { "description": "GDPR restricted - unable to process due to GDPR regulations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "statusCode": 451, "message": "We are unable to process this contact request due to our GDPR regulations" } } } }, "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" ] } } }, "Company": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the company, Required if no domain.", "example": "Lusha" }, "domain": { "type": "string", "description": "The domain of the company, Required if no name.", "example": "lusha.com" }, "isCurrent": { "type": "boolean", "description": "Indicates whether this is the person's current company", "example": true }, "jobTitle": { "type": "string", "description": "The job title of the person at the company", "example": "Software Engineer" }, "fqdn": { "type": "string", "description": "The fully qualified domain name of the company", "example": "https://lusha.com" }, "companySocialId": { "type": "string", "description": "The social ID associated with the company (if available)", "example": "1234567890" } }, "required": [ "isCurrent" ] }, "ContactSearchBulk": { "type": "object", "properties": { "contactId": { "type": "string", "description": "A unique sequential ID to associate with the contact object in the API response", "example": "1234" }, "personId": { "type": "string", "description": "The unique person identifier in Lusha", "example": "4183886134" }, "fullName": { "type": "string", "description": "The full name of the person", "example": "Dustin Moskovitz" }, "location": { "type": "string", "description": "The raw location of the person", "example": "Singapore,Chicago" }, "linkedinUrl": { "type": "string", "description": "The LinkedIn URL of the person", "example": "https://www.linkedin.com/in/dustin/" }, "email": { "type": "string", "description": "The email address of the person", "example": "dustin@lusha.com" }, "companies": { "description": "Details of the company where the contact is currently employed (or previously employed if applicable)", "type": "array", "items": { "$ref": "#/components/schemas/Company" } } }, "required": [ "contactId" ] }, "Metadata": { "type": "object", "properties": { "refreshJobInfo": { "type": "boolean", "description": "Set this to true to refresh job information for the contact. This replaces any outdated job details with the most current information. By default, Lusha returns results for records that have at least one of the specified contact details (e.g., phone number or email address).", "example": true }, "filterBy": { "type": "string", "description": "Filters the results based on specific contact details. Use the following options: emailAddresses, phoneNumbers", "example": "emailAddresses" }, "revealEmails": { "type": "boolean", "description": "Set `revealEmails=true` to retrieve only the email address of the contact.\n", "example": true }, "revealPhones": { "type": "boolean", "description": "Set `revealPhones=true` to retrieve only the phone number of the contact.\n", "example": true }, "signals": { "type": "array", "description": "Array of signal types to retrieve for the contact.\n- `allSignals`: All available signal types\n- `promotion`: Promotion signals\n- `companyChange`: Company change signals\n", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] }, "example": [ "promotion", "companyChange" ] }, "signalsStartDate": { "type": "string", "format": "date", "description": "Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.\n", "example": "2025-03-01" }, "partialProfile": { "type": "boolean", "description": "When set to true, returns a simplified contact profile with basic information only.\n", "default": false, "example": true } } }, "SearchBulkContactsRequest": { "type": "object", "properties": { "contacts": { "description": "This is a required parameter that should contain a list of contact objects. Each contact will be processed based on the provided contact details.", "type": "array", "items": { "$ref": "#/components/schemas/ContactSearchBulk" } }, "metadata": { "description": "Metadata for the search to filter the results", "$ref": "#/components/schemas/Metadata" } }, "required": [ "contacts" ] }, "ContactError": { "type": "object", "properties": { "code": { "type": "number", "description": "The code of the contact error", "example": 3 }, "name": { "type": "string", "description": "The name of the contact error", "example": "EMPTY_DATA" }, "message": { "type": "string", "description": "The message of the contact error", "example": "Could not find requested data" } } }, "EmailAddress": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address (alternative to 'address')", "example": "dustin@lusha.com" }, "address": { "type": "string", "description": "The email address (alternative to 'email')", "example": "dustin@lusha.com" }, "emailType": { "type": "string", "description": "The type of email address (alternative to 'type')", "example": "work", "enum": [ "work", "private" ] }, "emailConfidence": { "type": "string", "description": "The confidence level of the email address", "example": "A+" }, "updateDate": { "type": "string", "description": "The update date of the email address", "example": "2020-01-01" } } }, "PhoneNumbers": { "type": "object", "properties": { "number": { "type": "string", "description": "The phone number", "example": "+1234567890" }, "phoneType": { "type": "string", "description": "The type of phone number", "example": "Mobile", "enum": [ "Mobile", "Direct", "Phone" ] }, "doNotCall": { "type": "boolean", "description": "Indicates whether the phone number is listed as \"Do Not Call\" (DNC).", "example": false }, "updateDate": { "type": "string", "description": "The update date of the phone number", "example": "2020-01-01" } }, "required": [ "phoneType", "doNotCall", "updateDate" ] }, "LocationResponse": { "type": "object", "properties": { "country": { "type": "string", "description": "The country where the person is located.", "example": "Israel" }, "countryIso2": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the person.", "example": "IL" }, "country_iso2": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the person.", "example": "IL" }, "continent": { "type": "string", "description": "The continent where the person is located.", "example": "Asia" }, "rawLocation": { "type": "string", "example": "800 Boylston St, Suite 1410, Boston, MA 02199, US", "description": "The detailed address." }, "region": { "type": "string", "description": "The region where the person is located.", "example": "Tel Aviv" }, "city": { "type": "string", "description": "The city where the person is located.", "example": "Tel Aviv" }, "cityId": { "type": "number", "description": "The ID of the city where the person is located.", "example": 123 }, "state": { "type": "string", "description": "The state where the person is located.", "example": "Tel Aviv" }, "stateCode": { "type": "string", "description": "The state code of the person.", "example": "IL" }, "state_code": { "type": "string", "description": "The state code of the person.", "example": "IL" }, "street": { "type": "string", "description": "The street where the person is located.", "example": "123 Main St" }, "locationCoordinates": { "description": "The coordinates of the person.", "example": [ 32.0853, 34.7818 ], "type": "array", "items": { "type": "number" } }, "isEuContact": { "type": "boolean", "description": "Indicates whether the person is in the EU.", "example": true } }, "required": [ "country", "countryIso2", "continent", "rawLocation" ] }, "CompaniesBulkResponse": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CompanyBulkResponse" } }, "CompanyCrunchbaseResponse": { "type": "object", "properties": { "url": { "type": "string", "example": "https://crunchbase.com/company/lusha" } }, "required": [ "url" ] }, "CompanyLinkedinResponse": { "type": "object", "properties": { "url": { "type": "string", "example": "https://linkedin.com/company/lusha" } }, "required": [ "url" ] }, "CompanySocialResponse": { "type": "object", "properties": { "crunchbase": { "$ref": "#/components/schemas/CompanyCrunchbaseResponse" }, "linkedin": { "$ref": "#/components/schemas/CompanyLinkedinResponse" } } }, "CompanyLocationResponse": { "type": "object", "description": "HQ location only. For all company site locations, see companyLocations.", "properties": { "city": { "type": "string", "example": "Boston" }, "country": { "type": "string", "example": "United States" }, "fullLocation": { "type": "string", "example": "800 Boylston St, Suite 1410, Boston, Massachusetts 02199, US" }, "state": { "type": "string", "example": "Massachusetts" }, "stateCode": { "type": "string", "example": "MA" }, "countryIso2": { "type": "string", "example": "US" }, "rawLocation": { "type": "string", "example": "800 Boylston St; Suite 1410; Boston, Massachusetts 02199, US" } } }, "CompanySingleResponseData": { "type": "object", "properties": { "id": { "type": "number", "example": 123, "description": "A unique identifier for the Lusha company." }, "description": { "type": "string", "example": "Lusha is the sales intelligence platform designed to help businesses get their next customers.", "description": "A brief description of the company." }, "domain": { "type": "string", "example": "lusha.com", "description": "The domain name associated with the company's email addresses." }, "employees": { "type": "string", "example": "201 - 500", "description": "The company's employee size range." }, "founded": { "type": "string", "example": "August 1, 2011", "description": "The year the company was founded." }, "fqdn": { "type": "string", "example": "www.lusha.com", "description": "The fully qualified domain name of the company." }, "logoUrl": { "type": "string", "example": "https://logo.lusha.co/logo.jpg", "description": "The URL of the company's logo." }, "name": { "type": "string", "example": "Lusha", "description": "The name of the company." }, "linkedinFollowers": { "type": "integer", "description": "LinkedIn followers count for the company", "example": 1950 }, "emailDomain": { "type": "string", "description": "Company email domain", "example": "lusha.com" }, "companyLocations": { "type": "array", "description": "All known company locations (not just HQ). Key difference from existing HQ location fields — this includes all company site locations.", "items": { "type": "object", "properties": { "city": { "type": "string", "example": "Bucharest" }, "continent": { "type": "string", "example": "Europe" }, "country": { "type": "string", "example": "Romania" }, "country_iso2": { "type": "string", "example": "RO" }, "location_coordinates": { "type": "array", "items": { "type": "number" }, "example": [ 26.1062603, 44.432251 ] }, "state": { "type": "string", "nullable": true, "example": null }, "state_code": { "type": "string", "nullable": true, "example": null } } } }, "alternativeName": { "type": "string", "description": "Normalized alternative company name", "example": "lusha systems" }, "companyType": { "type": "string", "description": "Type of company", "example": "Private company" }, "lushaPopularityTier": { "type": "integer", "description": "A proprietary ranking used by Lusha to categorize companies based on their popularity in the platform", "example": 1 }, "companySize": { "type": "object", "description": "Company size details.", "properties": { "min": { "type": "number", "example": 11 }, "max": { "type": "number", "example": 50 }, "employeesInLinkedin": { "type": "number", "example": 32 } } }, "revenueRange": { "example": [ 1000000, 10000000 ], "description": "The company's revenue range.", "type": "array", "items": { "type": "number" } }, "mainIndustry": { "type": "string", "example": "Technology", "description": "The main industry of the company." }, "subIndustry": { "type": "string", "example": "Software", "description": "The specific sub-sector within the primary industry." }, "social": { "description": "Social media links associated with the company.", "$ref": "#/components/schemas/CompanySocialResponse" }, "address": { "type": "string", "example": "North America United States Boston 800 Boylston St , Suite 1410 , Boston, Massachusetts 02199, US Massachusetts US MA -71.05976867675781,42.358428955078125", "description": "The full address of the company's location." }, "location": { "description": "HQ location only. For all company site locations, see companyLocations.", "$ref": "#/components/schemas/CompanyLocationResponse" }, "categories": { "description": "LinkedIn industry tags for the company.", "example": [ "Technology", "Software" ], "type": "array", "items": { "type": "string" } }, "industryPrimaryGroupDetails": { "$ref": "#/components/schemas/CompanyIndustryPrimaryGroupDetails" }, "website": { "type": "string", "description": "The company's website URL.", "example": "https://lusha.com" }, "specialities": { "description": "LinkedIn specialties tags associated with the company.", "example": [ "data enrichment", "sales intelligence", "lead generation", "prospecting" ], "type": "array", "items": { "type": "string" } }, "funding": { "description": "Details regarding the company's funding activities.", "$ref": "#/components/schemas/CompanyFunding" }, "intent": { "description": "A list of detected intent topics related to the company based on your account's mapped topics.", "$ref": "#/components/schemas/CompanyIntent" }, "technologies": { "description": "A list of technologies associated with the company.", "type": "array", "items": { "$ref": "#/components/schemas/CompanyTechnology" } }, "riskNews": { "type": "array", "description": "Litigations and security news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "commercialActivityNews": { "type": "array", "description": "Launches, partnerships, and go-to-market activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "corporateStrategyNews": { "type": "array", "description": "M&A, restructuring, or strategic direction change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "financialEventsNews": { "type": "array", "description": "Funding, IPOs, and financial performance event signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "peopleNews": { "type": "array", "description": "Hiring, layoffs, or leadership change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "marketIntelligenceNews": { "type": "array", "description": "Event participation, recognition, and competitor activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "productActivityNews": { "type": "array", "description": "Product launch, development, and integration news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "surgeInHiring": { "type": "array", "description": "Overall hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringSignal" } }, "surgeInHiringByDepartment": { "type": "array", "description": "Department-specific hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByDepartmentSignal" } }, "surgeInHiringByLocation": { "type": "array", "description": "Location-specific hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByLocationSignal" } }, "websiteTrafficIncrease": { "type": "array", "description": "Website traffic increase signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "websiteTrafficDecrease": { "type": "array", "description": "Website traffic decrease signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "itSpendIncrease": { "type": "array", "description": "IT spending increase signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "itSpendDecrease": { "type": "array", "description": "IT spending decrease signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "headcountIncrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } } }, "required": [ "id", "name" ] }, "CompanyErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Something went wrong" } }, "required": [ "message" ] }, "CompanySingleResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanySingleResponseData" }, "errors": { "$ref": "#/components/schemas/CompanyErrorResponse" }, "meta": { "type": "object", "description": "Currently returns an empty value; this field should be deprecated in future releases.", "example": {} } } }, "CountryFilter": { "type": "object", "properties": { "name": { "type": "string", "example": "United States" }, "code": { "type": "string", "example": "US" } }, "required": [ "name", "code" ] }, "LocationSearchRequest": { "type": "object", "properties": { "text": { "type": "string", "description": "Search text for location", "example": "un" } }, "required": [ "text" ] }, "LocationFilter": { "type": "object", "properties": { "continent": { "type": "string", "example": "North America" }, "country": { "type": "string", "example": "United States" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "New York" }, "country_grouping": { "type": "string", "example": "na" } } }, "CompanyNameSearchRequest": { "type": "object", "properties": { "text": { "type": "string", "description": "Search text for company name", "example": "lusha" } }, "required": [ "text" ] }, "CompanyNameResult": { "type": "object", "properties": { "companyId": { "type": "number", "example": 33222678 }, "name": { "type": "string", "example": "Lusha" }, "logoUrl": { "type": "string", "example": "https://logo.lusha.co/d/company_33222678_logo.jpg" }, "fqdn": { "type": "string", "example": "www.lusha.com" } } }, "IndustryLabel": { "type": "object", "properties": { "main_industry": { "type": "string", "example": "Hospitality" }, "main_industry_id": { "type": "number", "example": 1 }, "sub_industries": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "Other" }, "id": { "type": "number", "example": 778 } } } } } }, "CompanySizeRange": { "type": "object", "properties": { "min": { "type": "number", "example": 1 }, "max": { "type": "number", "example": 10 } } }, "RevenueRange": { "type": "object", "properties": { "min": { "type": "number", "example": 1 }, "max": { "type": "number", "example": 1000000 } } }, "CompanyLocationFilter": { "type": "object", "properties": { "country": { "type": "string", "example": "United States" }, "continent": { "type": "string", "example": "North America" }, "country_grouping": { "type": "string", "example": "na" } } }, "SicCode": { "type": "object", "properties": { "code": { "type": "string", "example": "1011" }, "label": { "type": "string", "example": "Iron ores" } } }, "NaicsCode": { "type": "object", "properties": { "code": { "type": "string", "example": "11" }, "label": { "type": "string", "example": "Agriculture, Forestry, Fishing and Hunting" } } }, "TechnologySearchRequest": { "type": "object", "properties": { "text": { "type": "string", "description": "Search text for technology", "example": "rss" } }, "required": [ "text" ] }, "Technology": { "type": "object", "properties": { "name": { "type": "string", "example": "rss" } } }, "PaginationParams": { "type": "object", "properties": { "page": { "type": "number", "description": "Page number (0-1000)", "minimum": 0, "maximum": 1000, "default": 0 }, "size": { "type": "number", "description": "Page size (10-50)", "minimum": 10, "maximum": 50, "default": 20 } } }, "ContactFilters": { "type": "object", "properties": { "include": { "type": "object", "properties": { "departments": { "type": "array", "items": { "type": "string" }, "example": [ "Engineering & Technical" ] }, "seniority": { "type": "array", "items": { "type": "integer" }, "example": [ 4, 5 ] }, "existing_data_points": { "type": "array", "items": { "type": "string" }, "example": [ "phone", "work_email" ] }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LocationFilter" } }, "jobTitles": { "type": "array", "items": { "type": "string" }, "example": [ "CTO", "Chief Technology Officer", "VP Engineering", "Senior Developer" ] }, "linkedinUrls": { "type": "array", "description": "Filter contacts by LinkedIn profile URLs", "items": { "type": "string" }, "example": [ "https://www.linkedin.com/in/justin-pernitz", "https://www.linkedin.com/in/andrewbarrettbettcher" ] }, "searchText": { "type": "string", "description": "Free-text search across contact fields", "example": "Amit" }, "signal": { "type": "object", "description": "Filter contacts by signal types (premium filter - charges apply per signal type)", "properties": { "names": { "type": "array", "description": "Signal types to filter by", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ], "example": [ "promotion", "companyChange" ] } }, "startDate": { "type": "string", "format": "date", "description": "Start date for signal detection (YYYY-MM-DD format)", "example": "2025-11-01" } } } }, "exclude": { "type": "object", "description": "Same structure as include, for exclusion filters" } } } }, "CompanyFilters": { "type": "object", "properties": { "include": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "example": [ "Apple" ] }, "domains": { "type": "array", "items": { "type": "string", "example": "lusha.com" } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "example": "United States" } } } }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyTechnology" }, "example": [ { "name": "Amazon" } ] }, "intentTopics": { "type": "array", "items": { "type": "string" }, "example": [ "Digital Sales" ] }, "sizes": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySizeRange" } }, "revenues": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueRange" } }, "sicCodes": { "type": "array", "items": { "type": "string" }, "example": [ "1011", "1021" ] }, "naicsCodes": { "type": "array", "items": { "type": "string" }, "example": [ "11", "21" ] }, "mainIndustriesIds": { "type": "array", "items": { "type": "number" }, "example": [ 4, 5 ] }, "subIndustriesIds": { "type": "array", "items": { "type": "number" }, "example": [ 101 ] }, "searchText": { "type": "string", "description": "Free-text search across company fields", "example": "Finance Marketing in Germany DE" }, "excludePartialCompanies": { "type": "boolean", "example": false }, "companyLocations": { "type": "array", "description": "Filter by company **site-level office locations** as reported by LinkedIn.\nThis includes all physical office locations where the company has a presence.\n\n> **Important:** This is distinct from the `locations` filter, which matches against\n**HQ location only**. Use `companyLocations` when you want to find companies\nwith offices in a specific region regardless of where their headquarters is.\n", "items": { "$ref": "#/components/schemas/CompanyLocationFilter2" }, "example": [ { "country": "United States", "state": "California" }, { "country": "Germany" } ] }, "employeesInLinkedIn": { "$ref": "#/components/schemas/EmployeesInLinkedInFilter" }, "signal": { "type": "object", "description": "Filter companies by signal types (premium filter - charges apply per signal type).\n\nFor signal filtering. See the [Signal Options](https://docs.lusha.com/apis/openapi/signals/getsignaloptions) for available signal types.\n", "properties": { "names": { "type": "array", "description": "Signal types to filter by", "items": { "type": "string", "enum": [ "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": [ "commercialActivityNews", "financialEventsNews" ] }, "startDate": { "type": "string", "format": "date", "description": "Start date for signal detection (YYYY-MM-DD format)", "example": "2025-11-01" } } } } }, "exclude": { "type": "object", "description": "Same structure as include, for exclusion filters" } } }, "ContactSearchRequest": { "type": "object", "properties": { "includePartialContact": { "type": "boolean", "description": "When set to true, includes contacts with partial information in the search results.\nPartial contacts may have incomplete data but can still be valuable prospects.\n", "default": true, "example": false }, "excludeDnc": { "type": "boolean", "description": "When `true`, excludes contacts whose phones are all marked Do Not Call (DNC). Contacts with at least one callable phone appear in results; only callable phones are returned (DNC phones are hidden). Contacts with only DNC phones are excluded entirely.\n", "default": false, "example": true }, "pages": { "$ref": "#/components/schemas/PaginationParams" }, "filters": { "type": "object", "properties": { "contacts": { "$ref": "#/components/schemas/ContactFilters" }, "companies": { "$ref": "#/components/schemas/CompanyFilters" } } } }, "required": [ "filters" ] }, "ContactSearchData": { "type": "object", "properties": { "contactId": { "type": "string", "description": "A unique serial contact ID generated for each search response", "example": "06de9b18-516d-5512-5cb5-6ec5pb215776" }, "isShown": { "type": "boolean", "description": "Indicates whether the contact was already revealed by any of the account users", "example": false }, "name": { "type": "string", "description": "The full name of the contact", "example": "Chris Karageorge" }, "jobTitle": { "type": "string", "description": "The job title held by the person at their current company", "example": "Senior Director of Technical Operations" }, "companyId": { "type": "number", "description": "A unique identifier for a Lusha company", "example": 28054532 }, "companyName": { "type": "string", "description": "The name of the company where the person currently works", "example": "Lusha" }, "fqdn": { "type": "string", "description": "The fqdn of the company", "example": "lusha.com" }, "companyDescription": { "type": "string", "description": "A description of the company", "example": "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.\\n\\nLusha’s Sales Streaming Platform is built around Sales Playlists that continuously fill up with their ideal prospects – think “Spotify for sales.” With AI doing the heavy lifting, Lusha uncovers great-fit leads salespeople never knew existed and executes tailored, perfectly timed cadences that get meetings booked. And the more you use Lusha, the smarter it gets.\\n\\nWith Sales Streaming, salespeople spend most of their time face-to-face with relevant prospects, driving 4-6X more business." }, "logoUrl": { "type": "string", "description": "The URL of the company's logo", "example": "https://logo.lusha.co/brightdata/year=2024/month=04/day=30/j_lvlvj2vh1yv1ee0hye.b098e8301e8d32c12d1c8949a0624ba44761f995.file_lvlwjpb62juzpfz0l2.logo_cached.jpg" }, "hasCompanyEmployeesCount": { "type": "boolean" }, "hasCompanyRevenue": { "type": "boolean" }, "hasCompanyMainIndustry": { "type": "boolean" }, "hasCompanySubIndustry": { "type": "boolean" }, "hasCompanyFunding": { "type": "boolean" }, "hasCompanyIntent": { "type": "boolean" }, "hasCompanyTechnologies": { "type": "boolean" }, "hasDepartment": { "type": "boolean" }, "hasSeniority": { "type": "boolean" }, "hasContactLocation": { "type": "boolean" }, "hasSocialLink": { "type": "boolean" }, "hasEmails": { "type": "boolean" }, "hasWorkEmail": { "type": "boolean" }, "hasPrivateEmail": { "type": "boolean" }, "hasPhones": { "type": "boolean" }, "hasMobilePhone": { "type": "boolean" }, "hasDirectPhone": { "type": "boolean" }, "hasCompanyCity": { "type": "boolean" }, "hasCompanyCountry": { "type": "boolean" }, "signalTypes": { "type": "array", "description": "Types of signals detected for this contact", "items": { "type": "string" }, "example": [ "companyChange", "promotion" ] } } }, "ContactSearchResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The unique request ID used for subsequent enrichment requests" }, "currentPage": { "type": "number", "description": "The current page of the search results" }, "pageLength": { "type": "number", "description": "The number of results on the page" }, "totalResults": { "type": "number", "description": "The total number of search results" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactSearchData" } } } }, "ContactEnrichRequest": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The requestId generated in the Prospecting Search response (UUID)", "example": "b6effae6-35b8-493d-91aa-7d3b1b7c7dc7" }, "contactIds": { "type": "array", "description": "An array containing the contact IDs for enrichment. Min 1, max 100.", "items": { "type": "string" }, "example": [ "37b4c536-eaec-11ef-ad4b-a75f8e9e1484" ] }, "revealEmails": { "type": "boolean", "description": "Set `revealEmails=true` to retrieve only the email address of the contact.\nOnly available to customers on the **Unified Credits** pricing plan.\n", "example": false }, "revealPhones": { "type": "boolean", "description": "Set `revealPhones=true` to retrieve only the phone number of the contact.\nOnly available to customers on the **Unified Credits** pricing plan.\n", "example": true } }, "required": [ "requestId", "contactIds" ] }, "ContactEnrichData": { "type": "object", "properties": { "firstName": { "type": "string", "example": "Carolina" }, "lastName": { "type": "string", "example": "Portela" }, "fullName": { "type": "string", "example": "Carolina Portela" }, "isShown": { "type": "boolean", "example": false }, "jobTitle": { "type": "string", "example": "Solutions Engineer" }, "location": { "type": "object", "properties": { "city": { "type": "string", "example": "Boston" }, "state": { "type": "string", "example": "Massachusetts" }, "country": { "type": "string", "example": "United States" }, "country_iso2": { "type": "string", "example": "US" }, "continent": { "type": "string", "example": "North America" } } }, "emailAddresses": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } }, "phoneNumbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumbers" } }, "companyId": { "type": "number", "example": 3553744 }, "companyName": { "type": "string", "example": "Lusha" }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/carolinaportela/" }, "xUrl": { "type": "string", "example": "https://twitter.com/carolina" } } }, "departments": { "type": "array", "items": { "type": "string", "example": "Engineering & Technical" } }, "seniority": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "example": 4 }, "value": { "type": "string", "example": "senior" } } } }, "company": { "type": "object", "properties": { "revenueRange": { "type": "array", "items": { "type": "number" } }, "funding": { "$ref": "#/components/schemas/CompanyFunding" }, "intent": { "$ref": "#/components/schemas/CompanyIntent" }, "mainIndustry": { "type": "string" }, "subIndustry": { "type": "string" }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyTechnology" } } } }, "linkedinFollowersCount": { "type": "integer", "description": "Number of followers on LinkedIn", "example": 1250 }, "linkedinConnectionsCount": { "type": "integer", "description": "Number of LinkedIn connections", "example": 500 }, "linkedinCertifications": { "description": "Professional certifications listed on LinkedIn", "type": "array", "items": { "$ref": "#/components/schemas/LinkedinCertification" } }, "linkedinCourses": { "description": "Courses listed on LinkedIn profile", "type": "array", "items": { "$ref": "#/components/schemas/LinkedinCourse" } }, "linkedinAwards": { "description": "Honors and awards listed on LinkedIn profile", "type": "array", "items": { "$ref": "#/components/schemas/LinkedinAward" } }, "linkedinSkills": { "description": "Skills listed on LinkedIn profile", "type": "array", "items": { "type": "string" }, "example": [ "Microsoft Office", "Project Management", "Strategic Planning" ] } } }, "ContactEnrichResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The requestId that was used in the request" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact from the enrichment request" }, "isSuccess": { "type": "boolean", "description": "Indicates whether the enrichment process was successful" }, "data": { "$ref": "#/components/schemas/ContactEnrichData" } } } } } }, "CompanySearchRequest": { "type": "object", "properties": { "pages": { "$ref": "#/components/schemas/PaginationParams" }, "filters": { "type": "object", "properties": { "companies": { "$ref": "#/components/schemas/CompanyFilters" } } } }, "required": [ "filters" ] }, "CompanySearchData": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for a Lusha company" }, "name": { "type": "string", "description": "The name of the company" }, "fqdn": { "type": "string", "description": "The fqdn of the company" }, "description": { "type": "string", "description": "A description of the company" }, "logoUrl": { "type": "string", "description": "The URL of the company's logo" }, "hasCompanyEmployeesCount": { "type": "boolean" }, "hasCompanyRevenue": { "type": "boolean" }, "hasCompanyMainIndustry": { "type": "boolean" }, "hasCompanySubIndustry": { "type": "boolean" }, "hasCompanyFunding": { "type": "boolean" }, "hasCompanyIntent": { "type": "boolean" }, "hasCompanyTechnologies": { "type": "boolean" }, "hasCompanyCity": { "type": "boolean" }, "hasCompanyCountry": { "type": "boolean" }, "signalTypes": { "type": "array", "description": "Types of signals detected for this company", "items": { "type": "string" }, "example": null } } }, "CompanySearchResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The requestId that should be used in Prospecting Enrich request API params" }, "currentPage": { "type": "number", "description": "Current page of search results" }, "pageLength": { "type": "number", "description": "Page length" }, "totalResults": { "type": "number", "description": "Total search results" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchData" } } } }, "CompanyEnrichRequest": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The requestId from the Prospecting Search response", "example": "5ad275c8-7dd4-462a-bd45-6bc1970da64e" }, "companiesIds": { "type": "array", "description": "An array of company IDs for enrichment. Min 1, max 100.", "items": { "type": "string" }, "example": [ "1586" ] } }, "required": [ "requestId", "companiesIds" ] }, "CompanyEnrichData": { "type": "object", "properties": { "id": { "type": "number", "example": 33222678 }, "name": { "type": "string", "example": "Lusha" }, "companySize": { "type": "object", "properties": { "min": { "type": "number", "example": 11 }, "max": { "type": "number", "example": 50 }, "employees_in_linkedin": { "type": "number", "example": 32 } } }, "employees": { "type": "string", "example": "10001 - 100000" }, "revenueRange": { "type": "array", "items": { "type": "number" }, "example": [ 10000000, 50000000 ] }, "fqdn": { "type": "string", "example": "www.lusha.com" }, "description": { "type": "string", "example": "Lusha is the sales intelligence platform designed to help businesses get their next customers." }, "domains": { "type": "object", "properties": { "email": { "type": "string", "example": "lusha.com" }, "homepage": { "type": "string", "example": "lusha.com" } } }, "logoUrl": { "type": "string", "example": "https://logo.lusha.co/logo.jpg" }, "industryTags": { "type": "array", "items": { "type": "string", "example": [ "Technology, Information & Media", "Software Development" ] } }, "stateCode": { "type": "string", "example": "MA" }, "social": { "type": "object", "properties": { "linkedin": { "type": "string", "example": "https://www.linkedin.com/company/lushadata" }, "crunchbase": { "type": "string", "example": "https://www.crunchbase.com/organization/lusha" } } }, "city": { "type": "string", "example": "Boston" }, "state": { "type": "string", "example": "Massachusetts" }, "country": { "type": "string", "example": "United States" }, "countryIso2": { "type": "string", "example": "US" }, "continent": { "type": "string", "example": "North America" }, "rawLocation": { "type": "string", "example": "800 Boylston St; Suite 1410; Boston, Massachusetts 02199, US" }, "coordinates": { "type": "array", "items": { "type": "number" }, "example": [ -71.05976867675781, 42.358428955078125 ] }, "specialities": { "type": "array", "items": { "type": "string" }, "example": [ "data enrichment", "sales intelligence", "lead generation", "prospecting" ] }, "mainIndustry": { "type": "string", "example": "Technology, Information & Media" }, "subIndustry": { "type": "string", "example": "Software Development" }, "linkedinFollowers": { "type": "integer", "description": "LinkedIn followers count for the company", "example": 1950 }, "emailDomain": { "type": "string", "description": "Company email domain", "example": "bitcoinromania.ro" }, "companyLocations": { "type": "array", "description": "All known company locations (not just HQ)", "items": { "type": "object", "properties": { "city": { "type": "string" }, "continent": { "type": "string" }, "country": { "type": "string" }, "country_iso2": { "type": "string" }, "location_coordinates": { "type": "array", "items": { "type": "number" } }, "state": { "type": "string", "nullable": true }, "state_code": { "type": "string", "nullable": true } } } }, "alternativeName": { "type": "string", "description": "Normalized alternative company name", "example": "bitcoin romania" }, "companyType": { "type": "string", "description": "Type of company", "example": "Private company" }, "lushaPopularityTier": { "type": "integer", "description": "A proprietary ranking used by Lusha to categorize companies based on their popularity in the platform", "example": 1 }, "funding": { "$ref": "#/components/schemas/CompanyFunding" }, "intent": { "$ref": "#/components/schemas/CompanyIntent" }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyTechnology" } }, "riskNews": { "type": "array", "description": "Litigations and security news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "commercialActivityNews": { "type": "array", "description": "Launches, partnerships, and go-to-market activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "corporateStrategyNews": { "type": "array", "description": "M&A, restructuring, or strategic direction change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "financialEventsNews": { "type": "array", "description": "Funding, IPOs, and financial performance event signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "peopleNews": { "type": "array", "description": "Hiring, layoffs, or leadership change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "marketIntelligenceNews": { "type": "array", "description": "Event participation, recognition, and competitor activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "productActivityNews": { "type": "array", "description": "Product launch, development, and integration news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "surgeInHiring": { "type": "array", "description": "Overall hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringSignal" } }, "surgeInHiringByDepartment": { "type": "array", "description": "Department-specific hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByDepartmentSignal" } }, "surgeInHiringByLocation": { "type": "array", "description": "Location-specific hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByLocationSignal" } }, "websiteTrafficIncrease": { "type": "array", "description": "Website traffic increase signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "websiteTrafficDecrease": { "type": "array", "description": "Website traffic decrease signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "itSpendIncrease": { "type": "array", "description": "IT spending increase signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "itSpendDecrease": { "type": "array", "description": "IT spending decrease signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "headcountIncrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } } } }, "CompanyEnrichResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The requestId used in the request" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyEnrichData" } } } }, "JobTitle": { "type": "object", "properties": { "seniority": { "type": "string", "description": "The seniority of the person.", "example": "Director" }, "title": { "type": "string", "description": "The title of the person.", "example": "Director of Platform" }, "departments": { "description": "The departments of the person.", "example": [ "Engineering", "Operations" ], "type": "array", "items": { "type": "string" } } }, "required": [ "seniority", "title", "departments" ] }, "PreviousJobResponse": { "type": "object", "properties": { "jobTitle": { "description": "The job title of the person", "$ref": "#/components/schemas/JobTitle" }, "company": { "description": "The company of the person", "$ref": "#/components/schemas/Company" } }, "required": [ "jobTitle", "company" ] }, "SocialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "description": "The LinkedIn URL of the person", "example": "https://www.linkedin.com/in/dustin/" }, "xUrl": { "type": "string", "description": "The Twitter/X profile URL of the person", "example": "https://twitter.com/dustin" } }, "required": [ "linkedin" ] }, "LinkedinCertification": { "type": "object", "properties": { "companyId": { "type": "integer", "description": "Company ID that issued the certification", "example": 1035 }, "companyName": { "type": "string", "description": "Name of the company/organization that issued the certification", "example": "Microsoft" }, "credentialId": { "type": "string", "description": "Credential ID for verification", "example": "abc123" }, "dateMonth": { "description": "Month the certification was obtained", "example": 6, "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "dateYear": { "description": "Year the certification was obtained", "example": 2020, "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "expireDateMonth": { "description": "Month the certification expires", "example": 6, "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "expireDateYear": { "description": "Year the certification expires", "example": 2025, "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "linkedinCompanyId": { "type": "integer", "nullable": true, "description": "LinkedIn company ID", "example": 1441 }, "summary": { "type": "string", "nullable": true, "description": "Description of the certification", "example": "Azure fundamentals certification covering cloud concepts" }, "title": { "type": "string", "description": "Title/name of the certification", "example": "Microsoft Certified: Azure Fundamentals" }, "verifyUrl": { "type": "string", "nullable": true, "description": "URL to verify the certification", "example": "https://www.youracclaim.com/badges/5ccf865c-dd6e-4dcc-9184-c8999d31f83d" } } }, "LinkedinCourse": { "type": "object", "properties": { "activities": { "type": "string", "nullable": true, "description": "Activities" }, "degree": { "type": "string", "nullable": true, "description": "Degree" }, "endDate": { "type": "string", "nullable": true, "description": "End date" }, "endDateMonth": { "description": "End month", "oneOf": [ { "type": "integer", "nullable": true }, { "type": "string", "nullable": true } ] }, "endDateYear": { "description": "End year", "oneOf": [ { "type": "integer", "nullable": true }, { "type": "string", "nullable": true } ] }, "fieldOfStudy": { "type": "object", "nullable": true, "description": "Field of study object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "grade": { "type": "string", "nullable": true, "description": "Grade" }, "incompleteEducation": { "type": "boolean", "nullable": true, "description": "Incomplete education flag" }, "notes": { "type": "string", "nullable": true, "description": "Notes" }, "school": { "type": "object", "nullable": true, "description": "School information", "properties": { "createdAt": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true } } }, "startDate": { "type": "string", "nullable": true, "description": "Start date" }, "startDateMonth": { "description": "Start month", "oneOf": [ { "type": "number", "nullable": true }, { "type": "string", "nullable": true } ] }, "startDateYear": { "description": "Start year", "oneOf": [ { "type": "number", "nullable": true }, { "type": "string", "nullable": true } ] }, "linkedinSchoolId": { "type": "number", "nullable": true, "description": "LinkedIn school ID" } } }, "LinkedinAward": { "type": "object", "properties": { "companyName": { "type": "string", "nullable": true, "description": "Name of the organization that gave the award", "example": "Columbia Southern University" }, "dateDay": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Day the award was received", "example": 15 }, "dateMonth": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Month the award was received", "example": 7 }, "dateYear": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Year the award was received", "example": 2023 }, "linkedinCompanyId": { "type": "string", "nullable": true, "description": "LinkedIn company ID" }, "summary": { "type": "string", "nullable": true, "description": "Description of the award", "example": "Certificate of Recognition for Exceptional Teaching" }, "title": { "type": "string", "description": "Title/name of the award", "example": "Raising the Bar Award" } } }, "ContactTag": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact tag", "example": "123" }, "name": { "type": "string", "description": "The name of the contact tag", "example": "Prospect" }, "color": { "type": "string", "description": "The color of the contact tag", "example": "#000000" } }, "required": [ "id", "name", "color" ] }, "Contact": { "type": "object", "properties": { "companyId": { "type": "number", "description": "A unique identifier for the company on Lusha", "example": 123 }, "firstName": { "type": "string", "description": "The first name of the person", "example": "Dustin" }, "lastName": { "type": "string", "description": "The last name of the person", "example": "Moskovitz" }, "fullName": { "type": "string", "description": "The full name of the person", "example": "Dustin Moskovitz" }, "emails": { "description": "Simple array of email addresses (deprecated - use emailAddresses)", "type": "array", "items": { "type": "string" }, "example": [ "john.doe@example.com" ] }, "emailAddresses": { "description": "Detailed email addresses with metadata", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } }, "phones": { "description": "Simple array of phone numbers (deprecated - use phoneNumbers)", "type": "string", "example": "+1 555-123-4567" }, "phoneNumbers": { "description": "Detailed phone numbers with metadata", "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumbers" } }, "personId": { "type": "number", "description": "The unique person identifier in Lusha", "example": 123456 }, "location": { "description": "The location of the person", "$ref": "#/components/schemas/LocationResponse" }, "jobTitle": { "description": "The job title of the person", "$ref": "#/components/schemas/JobTitle" }, "socialLinks": { "description": "The social links of the person", "$ref": "#/components/schemas/SocialLinks" }, "jobStartDate": { "type": "string", "description": "The start date at current position", "example": "2020-01-01" }, "previousJob": { "description": "The previous job of the person", "$ref": "#/components/schemas/PreviousJobResponse" }, "contactTags": { "description": "Tags associated with the contact", "type": "array", "items": { "$ref": "#/components/schemas/ContactTag" } }, "updateDate": { "type": "string", "description": "The last update date of the contact data", "example": "2020-01-01" }, "linkedinFollowersCount": { "type": "integer", "description": "Number of followers on LinkedIn", "example": 1250 }, "linkedinConnectionsCount": { "type": "integer", "description": "Number of LinkedIn connections", "example": 500 }, "linkedinCertifications": { "description": "Professional certifications listed on LinkedIn", "type": "array", "items": { "$ref": "#/components/schemas/LinkedinCertification" } }, "linkedinCourses": { "description": "Courses listed on LinkedIn profile", "type": "array", "items": { "$ref": "#/components/schemas/LinkedinCourse" } }, "linkedinAwards": { "description": "Honors and awards listed on LinkedIn profile", "type": "array", "items": { "$ref": "#/components/schemas/LinkedinAward" } }, "linkedinSkills": { "description": "Skills listed on LinkedIn profile", "type": "array", "items": { "type": "string" }, "example": [ "Microsoft Office", "Project Management", "Strategic Planning" ] } }, "required": [ "companyId", "firstName", "lastName", "fullName" ] }, "ContactResponse": { "type": "object", "properties": { "error": { "description": "The error of the contact", "$ref": "#/components/schemas/ContactError" }, "isCreditCharged": { "type": "boolean", "description": "Indicates whether a credit charge was made for the contact", "example": true }, "data": { "description": "The data of the contact", "$ref": "#/components/schemas/Contact" } }, "required": [ "error", "isCreditCharged" ] }, "SocialResponse": { "type": "object", "properties": { "linkedin": { "type": "string", "description": "The LinkedIn URL of the person", "example": "https://www.linkedin.com/in/dustin/" }, "crunchbase": { "type": "string", "description": "The Crunchbase URL of the person", "example": "https://www.crunchbase.com/person/dustin-moskovitz" }, "twitter": { "type": "string", "description": "The Twitter URL of the person", "example": "https://twitter.com/dustin" }, "facebook": { "type": "string", "description": "The Facebook URL of the person", "example": "https://www.facebook.com/dustin" } } }, "FundingDataRound": { "type": "object", "properties": { "announcedOn": { "type": "string", "description": "The announced on date of the funding data", "example": "2020-01-01" }, "leadInvestors": { "description": "The lead investors of the funding data", "example": [ "Investor 1", "Investor 2" ], "type": "array", "items": { "type": "string" } }, "currency": { "type": "string", "description": "The currency of the funding data", "example": "USD" }, "title": { "type": "string", "description": "The title of the funding data", "example": "Series A" }, "moneyRaised": { "type": "number", "description": "The money raised of the funding data", "example": 1000000 } }, "required": [ "currency", "title" ] }, "FundingData": { "type": "object", "properties": { "totalRounds": { "type": "number", "description": "The total rounds of the funding data", "example": 10 }, "totalRoundsAmount": { "type": "number", "description": "The total rounds amount of the funding data", "example": 1000000 }, "currency": { "type": "string", "description": "The currency of the funding data", "example": "USD" }, "isIpo": { "type": "boolean", "description": "Indicates whether the company is an IPO", "example": true }, "lastFundingEventDate": { "type": "string", "description": "The last funding event date of the funding data", "example": "2020-01-01" }, "lastFundingEventAmount": { "type": "number", "description": "The last funding event amount of the funding data", "example": 1000000 }, "lastFundingEventName": { "type": "string", "description": "The last funding event name of the funding data", "example": "Series A" }, "rounds": { "description": "The rounds of the funding data", "type": "array", "items": { "$ref": "#/components/schemas/FundingDataRound" } } }, "required": [ "totalRounds", "currency", "isIpo" ] }, "BuyerIntent": { "type": "object", "properties": { "topicCount": { "type": "integer", "description": "The topic count of the buyer intent", "example": 6 }, "detectedTopics": { "type": "array", "description": "The detected topics of the buyer intent", "items": { "$ref": "#/components/schemas/CompanyIntentTopic" } } }, "required": [ "topicCount", "detectedTopics" ] }, "IndustryPrimaryGroupDetailsResponse": { "type": "object", "properties": { "sicCodes": { "description": "The SIC codes of the industry primary group", "type": "array", "items": { "$ref": "#/components/schemas/CompanySic" } }, "naicsCodes": { "description": "The NAICS codes of the industry primary group", "type": "array", "items": { "$ref": "#/components/schemas/CompanyNaics" } } } }, "CompanyIndustryData": { "type": "object", "properties": { "mainIndustry": { "type": "string", "description": "The main industry of the company", "example": "Software" }, "subIndustry": { "type": "string", "description": "The sub industry of the company", "example": "Sales" } }, "required": [ "mainIndustry", "subIndustry" ] }, "CompanyResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the company", "example": "Lusha" }, "description": { "type": "string", "description": "The description of the company", "example": "Lusha is a company that provides a platform for companies to find and connect with potential customers." }, "domains": { "type": "object", "description": "The domains of the company", "properties": { "homepage": { "type": "string", "example": "https://www.lusha.com" }, "email": { "type": "string", "example": "contact@lusha.com" } } }, "homepageUrl": { "type": "string", "description": "The homepage URL of the company", "example": "https://www.lusha.com" }, "fqdn": { "type": "string", "description": "The FQDN of the company", "example": "lusha.com" }, "location": { "description": "The location of the company", "$ref": "#/components/schemas/LocationResponse" }, "companySize": { "description": "The size of the company", "example": [ 100, 1000 ], "type": "array", "items": { "type": "number" } }, "revenueRange": { "description": "The revenue range of the company", "example": [ 1000000, 10000000 ], "type": "array", "items": { "type": "number" } }, "industryPrimaryGroup": { "type": "string", "description": "The industry primary group of the company", "example": "Software" }, "logoUrl": { "type": "string", "description": "The logo URL of the company", "example": "https://www.lusha.com/logo.png" }, "social": { "description": "The social links of the company", "$ref": "#/components/schemas/SocialResponse" }, "specialities": { "description": "The specialities of the company", "example": [ "Software", "Sales" ], "type": "array", "items": { "type": "string" } }, "technologies": { "description": "The technologies of the company", "type": "array", "items": { "$ref": "#/components/schemas/CompanyTechnology" }, "example": [ { "name": "JavaScript" }, { "name": "Python" } ] }, "funding": { "description": "The funding data of the company", "$ref": "#/components/schemas/FundingData" }, "industry": { "description": "The industry of the company", "$ref": "#/components/schemas/CompanyIndustryData" }, "intent": { "description": "The intent of the company", "$ref": "#/components/schemas/BuyerIntent" }, "industryPrimaryGroupDetails": { "description": "The industry primary group details of the company", "$ref": "#/components/schemas/IndustryPrimaryGroupDetailsResponse" } }, "required": [ "name", "fqdn" ] }, "BulkPersonResponse": { "type": "object", "properties": { "contacts": { "type": "object", "description": "The contacts of the bulk person output, keyed by contactId", "additionalProperties": { "$ref": "#/components/schemas/ContactResponse" } }, "companies": { "type": "object", "description": "The companies of the bulk person output, keyed by companyId", "additionalProperties": { "$ref": "#/components/schemas/CompanyResponse" } } }, "required": [ "contacts", "companies" ] }, "ContactWithCompany": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object", "properties": { "company": { "description": "The company of the contact", "$ref": "#/components/schemas/CompanyResponse" } }, "required": [ "company" ] } ] }, "ContactSingleResponse": { "type": "object", "properties": { "error": { "nullable": true, "description": "The error of the contact", "$ref": "#/components/schemas/ContactError" }, "isCreditCharged": { "type": "boolean", "description": "Indicates whether a credit charge was made for the contact", "example": true }, "data": { "description": "The data of the contact and company", "$ref": "#/components/schemas/ContactWithCompany" } }, "required": [ "error", "isCreditCharged" ] }, "SingleContactResponse": { "type": "object", "properties": { "contact": { "description": "The contact response object", "$ref": "#/components/schemas/ContactSingleResponse" } }, "required": [ "contact" ] }, "UsageStats": { "type": "object", "properties": { "used": { "type": "number", "description": "The number of credits that have been consumed from the total available credits", "example": 10 }, "total": { "type": "number", "description": "The initial amount of credits your account started with", "example": 100 }, "remaining": { "type": "number", "description": "The number of credits left after subtracting the used credits from the total", "example": 90 } }, "required": [ "used", "total", "remaining" ] }, "AccountUsageStatsResponse": { "type": "object", "properties": { "usage": { "type": "object", "description": "The usage stats for the account", "additionalProperties": { "$ref": "#/components/schemas/UsageStats" } } }, "required": [ "usage" ] }, "CompanyBulkRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique sequential ID associated with each company. This ID is used to correlate the provided company object with the API response", "example": "1" }, "domain": { "type": "string", "description": "The domain name associated with the company", "example": "lusha.com" }, "fqdn": { "type": "string", "description": "The Fully Qualified Domain Name (FQDN) of the company." }, "name": { "type": "string", "description": "The name of the company", "example": "Lusha" }, "companyId": { "type": "string", "description": "A unique identifier for a Lusha company. Note: Values may be removed or merged. No management system exists to log historical changes for companyId. This field is intended for deprecation in the future.", "example": "1234567890" } }, "required": [ "id" ] }, "CompaniesBulkRequest": { "type": "object", "properties": { "companies": { "description": "The list of companies to search", "type": "array", "items": { "$ref": "#/components/schemas/CompanyBulkRequest" } }, "signals": { "type": "array", "description": "Array of signal types to retrieve for the companies.\n- `allSignals`: All available signal types\n\n> See [Signal Filters](https://docs.lusha.com/apis/openapi/signal-filters/getsignaloptions) for complete details on available signals and their categories\n", "items": { "type": "string", "enum": [ "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": [ "surgeInHiringByLocation" ] }, "signalsStartDate": { "type": "string", "format": "date", "description": "Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.\n", "example": "2025-03-01" }, "signalsFilters": { "type": "object", "description": "Optional filters to narrow signal results within the requested signal types.\n- Multi-value filters use **OR** logic\n- Filter values are **not** case-sensitive\n- Unrecognized values are **silently ignored**\n- `state` without `country` in `hiringByLocations` returns HTTP **400**\n", "properties": { "include": { "$ref": "#/components/schemas/CompanySignalFiltersInclude" } } }, "partialCompany": { "type": "boolean", "description": "Expand coverage with partial company profiles\n", "default": true, "example": false } }, "required": [ "companies" ] }, "CompanySic": { "type": "object", "properties": { "sicCodes": { "type": "number", "example": 1234 }, "description": { "type": "string", "example": "Software Publishing" } }, "required": [ "sic", "description" ] }, "CompanyNaics": { "type": "object", "properties": { "naicsCodes": { "type": "number", "example": 541511 }, "description": { "type": "string", "example": "Custom Computer Programming Services" } }, "required": [ "naics", "description" ] }, "CompanyIndustryPrimaryGroupDetails": { "type": "object", "properties": { "sicCodes": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySic" } }, "naicsCodes": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyNaics" } } } }, "CompanyFundingRound": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD", "description": "Currency of the funding round" }, "roundAmount": { "type": "number", "example": 205000000, "description": "Amount raised in the round" }, "roundType": { "type": "string", "example": "Private Equity Round", "description": "Type of funding round" }, "roundDate": { "type": "string", "example": "Nov 10, 2021", "description": "Date of the funding round" } }, "required": [ "currency", "roundAmount", "roundType", "roundDate" ] }, "CompanyFunding": { "type": "object", "properties": { "rounds": { "description": "List of funding rounds", "type": "array", "items": { "$ref": "#/components/schemas/CompanyFundingRound" } }, "totalRounds": { "type": "number", "example": 2, "description": "Total number of rounds" }, "totalRoundsAmount": { "type": "number", "example": 245000000, "description": "Total amount raised across all rounds" }, "currency": { "type": "string", "example": "USD", "description": "Currency used" }, "isIpo": { "type": "boolean", "example": false, "description": "Whether the company has gone public" }, "lastRoundType": { "type": "string", "example": "Private Equity Round", "description": "Type of the last funding round" }, "lastRoundAmount": { "type": "number", "example": 205000000, "description": "Amount of the last funding round" }, "lastRoundDate": { "type": "string", "example": "Nov 10, 2021", "description": "Date of the last funding round" } }, "required": [ "totalRounds", "currency", "isIpo" ] }, "CompanyIntentTopicMetadata": { "type": "object", "properties": { "topicScore": { "type": "number", "example": 83, "description": "Relevance score for the intent topic" }, "topicTrend": { "type": "string", "example": "-5", "description": "Trend of the topic (e.g., +1, -5, New)" } }, "required": [ "topicScore", "topicTrend" ] }, "CompanyIntentTopic": { "type": "object", "properties": { "topicName": { "type": "string", "example": "Remote Sales", "description": "Name of the intent topic" }, "metadata": { "$ref": "#/components/schemas/CompanyIntentTopicMetadata" } }, "required": [ "topicName", "metadata" ] }, "CompanyIntent": { "type": "object", "properties": { "detectedTopics": { "description": "Detected intent topics", "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntentTopic" } }, "topicCount": { "type": "number", "example": 6, "description": "Number of topics detected" } }, "required": [ "detectedTopics", "topicCount" ] }, "CompanyTechnology": { "type": "object", "properties": { "name": { "type": "string", "example": "salesforce", "description": "Technology name used by the company" } }, "required": [ "name" ] }, "CompanyBulkResponse": { "type": "object", "properties": { "id": { "type": "number", "example": 33222678, "description": "A unique identifier for the Lusha company." }, "lushaCompanyId": { "type": "string", "example": "16303253", "description": "Lusha's internal company identifier." }, "name": { "type": "string", "example": "Lusha", "description": "The name of the company." }, "companySize": { "example": [ 201, 500 ], "description": "The size range of the company, based on number of employees.", "type": "array", "items": { "type": "number" } }, "linkedinFollowers": { "type": "integer", "description": "LinkedIn followers count for the company", "example": 1950 }, "emailDomain": { "type": "string", "description": "Company email domain", "example": "bitcoinromania.ro" }, "companyLocations": { "type": "array", "description": "All known company locations (not just HQ). Key difference from existing HQ location fields — this includes all company site locations.", "items": { "type": "object", "properties": { "city": { "type": "string" }, "continent": { "type": "string" }, "country": { "type": "string" }, "country_iso2": { "type": "string" }, "location_coordinates": { "type": "array", "items": { "type": "number" } }, "state": { "type": "string", "nullable": true }, "state_code": { "type": "string", "nullable": true } } } }, "alternativeName": { "type": "string", "description": "Normalized alternative company name", "example": "bitcoin romania" }, "companyType": { "type": "string", "description": "Type of company", "example": "Private company" }, "lushaPopularityTier": { "type": "integer", "description": "A proprietary ranking used by Lusha to categorize companies based on their popularity in the platform", "example": 1 }, "employeesInLinkedin": { "type": "number", "description": "Number of employees listed on LinkedIn", "example": 32 }, "revenueRange": { "example": [ 10000000, 50000000 ], "description": "The company's revenue range.", "type": "array", "items": { "type": "number" } }, "fqdn": { "type": "string", "example": "www.lusha.com", "description": "The Fully Qualified Domain Name (FQDN) of the company." }, "founded": { "type": "string", "example": "2016", "description": "The date the company was founded." }, "description": { "type": "string", "example": "Lusha is the sales intelligence platform...", "description": "A brief description of the company." }, "logoUrl": { "type": "string", "example": "https://logo.lusha.co/logo.jpg", "description": "The URL of the company's logo." }, "industryPrimaryGroupDetails": { "$ref": "#/components/schemas/CompanyIndustryPrimaryGroupDetails", "description": "Primary industry classification details including SIC and NAICS codes." }, "linkedin": { "type": "string", "example": "https://www.linkedin.com/company/lushadata", "description": "The LinkedIn URL of the company." }, "mainIndustry": { "type": "string", "example": "Technology, Information & Media", "description": "The main industry category of the company." }, "subIndustry": { "type": "string", "example": "Software Development", "description": "The specific sub-industry of the company." }, "city": { "type": "string", "example": "Boston", "description": "The city where the company is located." }, "state": { "type": "string", "example": "Massachusetts", "description": "The state where the company is located." }, "country": { "type": "string", "example": "United States", "description": "The country where the company is located." }, "countryIso2": { "type": "string", "example": "US", "description": "The ISO 3166-1 alpha-2 country code." }, "continent": { "type": "string", "example": "North America", "description": "The continent where the company is located." }, "rawLocation": { "type": "string", "example": "800 Boylston St; Suite 1410; Boston, Massachusetts 02199, US", "description": "The full address of the company." }, "crunchbase": { "type": "string", "example": "https://www.crunchbase.com/organization/lusha", "description": "The Crunchbase URL of the company." }, "specialities": { "type": "array", "items": { "type": "string" }, "example": [ "data accuracy", "sales intelligence" ], "description": "Company specialties and focus areas." }, "funding": { "$ref": "#/components/schemas/CompanyFunding", "description": "Company funding information." }, "intent": { "$ref": "#/components/schemas/CompanyIntent", "description": "Company intent signals and topics." }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyTechnology" }, "description": "Technologies used by the company." }, "riskNews": { "type": "array", "description": "Litigations and security news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "commercialActivityNews": { "type": "array", "description": "Launches, partnerships, and go-to-market activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "corporateStrategyNews": { "type": "array", "description": "M&A, restructuring, or strategic direction change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "financialEventsNews": { "type": "array", "description": "Funding, IPOs, and financial performance event signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "peopleNews": { "type": "array", "description": "Hiring, layoffs, or leadership change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "marketIntelligenceNews": { "type": "array", "description": "Event participation, recognition, and competitor activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "productActivityNews": { "type": "array", "description": "Product launch, development, and integration news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "surgeInHiring": { "type": "array", "description": "Overall hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringSignal" } }, "surgeInHiringByDepartment": { "type": "array", "description": "Department-specific hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByDepartmentSignal" } }, "surgeInHiringByLocation": { "type": "array", "description": "Location-specific hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByLocationSignal" } }, "websiteTrafficIncrease": { "type": "array", "description": "Website traffic increase signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "websiteTrafficDecrease": { "type": "array", "description": "Website traffic decrease signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "itSpendIncrease": { "type": "array", "description": "IT spending increase signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "itSpendDecrease": { "type": "array", "description": "IT spending decrease signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "headcountIncrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } } } }, "ContactSignalsByIdRequest": { "type": "object", "required": [ "contactIds", "signals" ], "properties": { "contactIds": { "type": "array", "description": "List of contact IDs to retrieve signals for", "minItems": 1, "maxItems": 100, "items": { "type": "integer" }, "example": [ 115889 ] }, "signals": { "type": "array", "description": "Types of signals to retrieve", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] }, "example": [ "promotion", "companyChange" ] }, "startDate": { "type": "string", "format": "date", "description": "Start date for signal retrieval (YYYY-MM-DD format)", "example": "2025-03-01" }, "maxResultsPerSignal": { "type": "integer", "description": "Maximum number of signal instances to return per signal type per entity. Optional.\n\nDefault behavior when omitted:\n- No `startDate` provided: all available signals are returned\n- `startDate` provided: all signals from that date onward are returned\n", "example": 10 } } }, "ContactSignalsSearchRequest": { "type": "object", "required": [ "signals", "contacts" ], "properties": { "contacts": { "type": "array", "description": "List of contact identifiers to search for", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique sequential ID to associate with the contact object in the API response", "example": "12345" }, "social_link": { "type": "string", "format": "uri", "description": "LinkedIn profile URL", "example": "https://www.linkedin.com/in/ron-nabet" }, "full_name": { "type": "string", "description": "Full name of the contact", "example": "Ron Nabet" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "dustin@lusha.com" }, "companies": { "type": "array", "description": "Company associations", "items": { "type": "object", "required": [ "name", "domain" ], "properties": { "name": { "type": "string", "description": "Company name", "example": "Lusha" }, "domain": { "type": "string", "description": "Company domain (FQDN, not URL)", "example": "lusha.com" }, "is_current": { "type": "boolean", "description": "Whether this is the current company", "default": true, "example": true } } } } } } }, "signals": { "type": "array", "description": "Types of signals to retrieve", "items": { "type": "string", "enum": [ "allSignals", "promotion", "companyChange" ] }, "example": [ "promotion", "companyChange" ] }, "startDate": { "type": "string", "format": "date", "description": "Start date for signal retrieval (YYYY-MM-DD format)", "example": "2025-01-01" }, "maxResultsPerSignal": { "type": "integer", "description": "Maximum number of signal instances to return per signal type per entity. Optional.\n\nDefault behavior when omitted:\n- No `startDate` provided: all available signals are returned\n- `startDate` provided: all signals from that date onward are returned\n", "example": 10 } } }, "ContactSignal": { "type": "object", "properties": { "personId": { "type": "string", "description": "Contact person ID", "example": "115889" }, "currentCompanyId": { "type": "integer", "description": "Current company ID", "example": 8217 }, "currentCompanyName": { "type": "string", "description": "Current company name", "example": "Callaway Golf" }, "currentDepartments": { "type": "string", "description": "Current department", "example": "R&D" }, "currentSeniorityLabel": { "type": "string", "description": "Current seniority level", "example": "c-suite" }, "currentTitle": { "type": "string", "description": "Current job title", "example": "Senior Manager, IT Solutions" }, "signalDate": { "type": "string", "format": "date", "description": "Date when the signal occurred", "example": "2025-05-01" }, "previousCompanyName": { "type": "string", "description": "Previous company name (for company change signals)", "example": "Previous Corp" }, "previousDomain": { "type": "string", "description": "Previous company's homepage domain", "example": "nextgen.com" }, "currentDomain": { "type": "string", "description": "Current company's homepage domain", "example": "vendavo.com" } } }, "ContactSignalData": { "type": "object", "properties": { "personId": { "type": "string", "description": "Contact person ID", "example": "115889" }, "companyChange": { "type": "array", "description": "Company change signals", "items": { "$ref": "#/components/schemas/ContactSignal" } }, "promotion": { "type": "array", "description": "Promotion signals", "items": { "$ref": "#/components/schemas/ContactSignal" } } } }, "ContactSignalsByIdResponse": { "type": "object", "properties": { "contacts": { "type": "object", "description": "Map of contact IDs to their signals", "additionalProperties": { "$ref": "#/components/schemas/ContactSignalData" } }, "endDate": { "type": "string", "format": "date", "description": "End date of the signal period", "example": "2025-07-31" }, "startDate": { "type": "string", "format": "date", "description": "Start date of the signal period", "example": "2025-03-01" }, "creditCharged": { "type": "integer", "description": "Number of credits charged for this request", "example": 2 } } }, "ContactSignalsSearchResponse": { "type": "object", "properties": { "contacts": { "type": "object", "description": "Map of user-provided IDs to contact signals", "additionalProperties": { "type": "object", "properties": { "personId": { "type": "string", "description": "Contact person ID", "example": "115889" }, "companyChange": { "type": "array", "description": "Company change signals", "items": { "$ref": "#/components/schemas/ContactSignal" } }, "promotion": { "type": "array", "description": "Promotion signals", "items": { "$ref": "#/components/schemas/ContactSignal" } } } } }, "endDate": { "type": "string", "format": "date", "description": "End date of the signal period", "example": "2025-07-31" }, "startDate": { "type": "string", "format": "date", "description": "Start date of the signal period", "example": "2025-01-01" }, "creditCharged": { "type": "integer", "description": "Number of credits charged for this request", "example": 2 } } }, "SignalFilterLocation": { "type": "object", "description": "Location filter for hiring signals. `country` is required; `state` is optional.\nProviding `state` without `country` returns HTTP 400.\n", "required": [ "country" ], "properties": { "country": { "type": "string", "example": "United States" }, "state": { "type": "string", "example": "California" } } }, "CompanySignalFiltersInclude": { "type": "object", "description": "Optional sub-filters to narrow results within a signal type.\n- Multi-value filters use **OR** logic\n- Filter values are **not** case-sensitive\n- `state` without `country` in `hiringByLocations` returns HTTP **400**\n\n> See [Signal Options](#operation/getSignalOptions) for available enum values.\n", "properties": { "newsEventTypes": { "type": "array", "description": "Filter news signals by specific event types.", "items": { "type": "string", "enum": [ "Asset Investment", "Asset Sale", "Competitor Activity", "Event Participation", "Executive Departure", "Executive Hire", "Executive Promotion", "Facilities Expansion", "Facility Closure", "Funding Round", "Headcount Decrease", "Headcount Increase", "IPO", "Lawsuit Faced", "Lawsuit Filed", "M&A", "New Customer", "New Location", "New Vendor", "Partnership", "Product Development", "Product Integration", "Product Launch", "Recognition", "Security Issue", "Strategic Investment" ] }, "example": [ "Partnership", "New Customer" ] }, "hiringByDepartments": { "type": "array", "description": "Filter `surgeInHiringByDepartment` signals by department.", "items": { "type": "string", "enum": [ "Business Development", "Consulting", "Customer Service", "Engineering & Technical", "Finance", "General Management", "Health Care & Medical", "Human Resources", "Information Technology", "Legal", "Marketing", "Operations", "Other", "Product", "Research & Analytics", "Sales" ] }, "example": [ "Engineering & Technical", "Sales" ] }, "hiringByLocations": { "type": "array", "description": "Filter `surgeInHiringByLocation` signals by country/state.", "items": { "$ref": "#/components/schemas/SignalFilterLocation" }, "example": [ { "country": "United States", "state": "California" }, { "country": "Germany" } ] } } }, "CompanySignalsByIdRequest": { "type": "object", "required": [ "companyIds", "signals" ], "properties": { "companyIds": { "type": "array", "description": "List of company IDs to retrieve signals for", "minItems": 1, "maxItems": 100, "items": { "type": "integer" }, "example": [ 3416 ] }, "signals": { "type": "array", "description": "Types of signals to retrieve", "items": { "type": "string", "enum": [ "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": "websiteTrafficIncrease" }, "startDate": { "type": "string", "format": "date", "description": "Start date for signal retrieval (YYYY-MM-DD format)", "example": "2025-03-01" }, "maxResultsPerSignal": { "type": "integer", "description": "Maximum number of signal instances to return per signal type per entity. Optional.\n\nDefault behavior when omitted:\n- No `startDate` provided: all available signals are returned\n- `startDate` provided: all signals from that date onward are returned\n", "example": 10 }, "filters": { "type": "object", "description": "Optional filters to narrow signal results.", "properties": { "include": { "$ref": "#/components/schemas/CompanySignalFiltersInclude" } } } } }, "CompanySignalsSearchRequest": { "type": "object", "required": [ "companies", "signals" ], "properties": { "companies": { "type": "array", "description": "List of company identifiers to search for", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique sequential ID to associate with the company object in the API response", "example": "12345" }, "name": { "type": "string", "description": "Company name", "example": "Lusha" }, "domain": { "type": "string", "description": "Company domain", "example": "lusha.com" } } } }, "signals": { "type": "array", "description": "Types of signals to retrieve", "items": { "type": "string", "enum": [ "allSignals", "websiteTrafficIncrease", "websiteTrafficDecrease", "itSpendIncrease", "itSpendDecrease", "headcountIncrease1m", "headcountDecrease1m", "headcountIncrease3m", "headcountDecrease3m", "headcountIncrease6m", "headcountDecrease6m", "headcountIncrease12m", "headcountDecrease12m", "surgeInHiring", "surgeInHiringByDepartment", "surgeInHiringByLocation", "riskNews", "commercialActivityNews", "corporateStrategyNews", "financialEventsNews", "peopleNews", "marketIntelligenceNews", "productActivityNews" ] }, "example": [ "itSpendIncrease" ] }, "startDate": { "type": "string", "format": "date", "description": "Start date for signal retrieval (YYYY-MM-DD format)", "example": "2025-01-01" }, "maxResultsPerSignal": { "type": "integer", "description": "Maximum number of signal instances to return per signal type per entity. Optional.\n\nDefault behavior when omitted:\n- No `startDate` provided: all available signals are returned\n- `startDate` provided: all signals from that date onward are returned\n", "example": 10 }, "filters": { "type": "object", "description": "Optional filters to narrow signal results.", "properties": { "include": { "$ref": "#/components/schemas/CompanySignalFiltersInclude" } } } } }, "CompanySignal": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID", "example": "3416" }, "signalType": { "type": "string", "description": "Type of signal", "enum": [ "new_jobs_count", "open_jobs_count", "size_increase" ], "example": "new_jobs_count" }, "score": { "type": "string", "description": "Signal strength/importance", "enum": [ "high", "medium", "low" ], "example": "high" }, "signalDate": { "type": "string", "format": "date", "description": "Date when the signal occurred", "example": "2025-06-15" }, "historicalAvg": { "type": "number", "description": "Historical average value", "example": 15.5 }, "newValue": { "type": "number", "description": "New value after change", "example": 25 }, "oldValue": { "type": "number", "description": "Previous value before change", "example": 10 } } }, "NewsEventCategory": { "type": "string", "description": "News event category for filtering company news signals", "enum": null, "example": "allSignals" }, "CompanyNewsEventSignal": { "type": "object", "properties": { "companyId": { "type": "integer", "description": "Company ID", "example": 9506502 }, "eventType": { "type": "string", "description": "Specific type of news event", "example": "sued" }, "eventCategory": { "$ref": "#/components/schemas/NewsEventCategory" }, "eventEffectiveDate": { "type": "string", "format": "date", "nullable": true, "description": "Date when the event occurred or will occur", "example": "2025-10-28" }, "eventSummary": { "type": "string", "description": "Brief summary of the news event", "example": "Cameo filed suit against OpenAI on Oct 28th '25." }, "articleSentence": { "type": "string", "description": "Relevant sentence from the source article", "example": "Cameo, the startup known for personalized celebrity videos, filed a lawsuit Tuesday against OpenAI..." }, "articleUrl": { "type": "string", "format": "uri", "description": "URL of the source article", "example": "https://www.businessinsider.com/cameo-lawsuit-openai-copyright-infringement-sora-app-2025-10" }, "articleTitle": { "type": "string", "description": "Title of the source article", "example": "Cameo sues OpenAI for using 'Cameo' as the name for its virtual likeness function" }, "articlePublishedDate": { "type": "string", "format": "date", "description": "Publication date of the source article", "example": "2025-10-29" } } }, "CompanyWebsiteTrafficSignal": { "type": "object", "properties": { "companyId": { "type": "string", "example": "3416" }, "signalId": { "type": "string", "example": "1503902" }, "signalDate": { "type": "string", "format": "date", "example": "2025-06-15" }, "historicalAvg": { "type": "number", "description": "Historical average monthly visits", "example": 50000 }, "lastMonthVisits": { "type": "number", "description": "Visits in the last month", "example": 75000 }, "changeRatePercent": { "type": "number", "description": "Percentage change from historical average", "example": 50 }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "CompanyNewsSignal": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Lusha company identifier", "example": "33222678" }, "companyName": { "type": "string", "description": "Company name", "example": "Lusha" }, "domain": { "type": "string", "description": "Company domain", "example": "lusha.com" }, "signalId": { "type": "string", "description": "Signal identifier", "example": "1503910" }, "eventType": { "type": "string", "description": "Type of event", "example": "partnership" }, "eventSummary": { "type": "string", "description": "Summary of the event", "example": "Lusha announced a strategic partnership with Salesforce to integrate its data enrichment capabilities." }, "articlePublishedDate": { "type": "string", "format": "date", "description": "Publication date of the article", "example": "2025-06-15" }, "articleTitle": { "type": "string", "description": "Title of the article", "example": "Lusha Partners with Salesforce to Enhance CRM Data Quality" }, "articleHighlight": { "type": "string", "description": "Key highlight from the article", "example": "The partnership will enable Salesforce users to access Lusha's contact and company data directly within their CRM." }, "eventEffectiveDate": { "type": "string", "format": "date", "description": "Effective date of the event", "example": "2025-06-10" }, "articleUrl": { "type": "string", "format": "uri", "description": "URL to the source article", "example": "https://example.com/lusha-salesforce-partnership" } } }, "CompanyItSpendSignal": { "type": "object", "properties": { "companyId": { "type": "string", "example": "3416" }, "signalId": { "type": "string", "example": "1503903" }, "signalDate": { "type": "string", "format": "date", "example": "2025-06-15" }, "estimatedAnnualItSpend": { "type": "number", "description": "Estimated annual IT spending (USD)", "example": 5000000 }, "changeRatePercent": { "type": "number", "description": "Percentage change in IT spending", "example": 25 }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "CompanyHeadcountChangeSignal": { "type": "object", "properties": { "companyId": { "type": "string", "example": "3416" }, "signalId": { "type": "string", "example": "1503904" }, "signalDate": { "type": "string", "format": "date", "example": "2025-06-15" }, "baselineEmployeesCount": { "type": "number", "description": "Employee count at baseline", "example": 500 }, "newEmployeesCount": { "type": "number", "description": "Current employee count", "example": 550 }, "changeRatePercent": { "type": "number", "description": "Percentage change", "example": 10 }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "CompanySurgeInHiringSignal": { "type": "object", "properties": { "companyId": { "type": "string", "example": "3416" }, "signalId": { "type": "string", "example": "1503905" }, "signalDate": { "type": "string", "format": "date", "example": "2025-06-15" }, "newJobsPostedLastWeek": { "type": "number", "description": "Jobs posted in the last week", "example": 25 }, "historicalAvg": { "type": "number", "description": "Historical weekly average", "example": 10 }, "changeRatePercent": { "type": "number", "description": "Percentage increase", "example": 150 }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "CompanySurgeInHiringByDepartmentSignal": { "type": "object", "properties": { "signalId": { "type": "string", "example": "1503906" }, "companyId": { "type": "string", "example": "3416" }, "department": { "type": "string", "description": "Department with hiring surge", "example": "Engineering" }, "signalDate": { "type": "string", "format": "date", "example": "2025-06-15" }, "newJobsPostedLast4Weeks": { "type": "number", "description": "Jobs posted in last 4 weeks for this department", "example": 15 }, "historicalAvg": { "type": "number", "description": "Historical 4-week average for this department", "example": 5 }, "changeRatePercent": { "type": "number", "description": "Percentage increase", "example": 200 }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "CompanySurgeInHiringByLocationSignal": { "type": "object", "properties": { "signalId": { "type": "string", "example": "1503907" }, "companyId": { "type": "string", "example": "3416" }, "country": { "type": "string", "description": "Country with hiring surge", "example": "United States" }, "state": { "type": "string", "description": "State/region with hiring surge", "example": "California" }, "signalDate": { "type": "string", "format": "date", "example": "2025-06-15" }, "newJobsPostedLast4Weeks": { "type": "number", "description": "Jobs posted in last 4 weeks for this location", "example": 20 }, "historicalAvg": { "type": "number", "description": "Historical 4-week average for this location", "example": 8 }, "changeRatePercent": { "type": "number", "description": "Percentage increase", "example": 150 }, "companyName": { "type": "string", "example": "Lusha" }, "domain": { "type": "string", "example": "lusha.com" } } }, "CompanySignalData": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID", "example": "3416" }, "companyName": { "type": "string", "description": "Name of the company", "example": "Lusha" }, "domain": { "type": "string", "description": "Company domain", "example": "lusha.com" }, "riskNews": { "type": "array", "description": "Litigations and security news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "commercialActivityNews": { "type": "array", "description": "Launches, partnerships, and go-to-market activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "corporateStrategyNews": { "type": "array", "description": "M&A, restructuring, or strategic direction change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "financialEventsNews": { "type": "array", "description": "Funding, IPOs, and financial performance event signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "peopleNews": { "type": "array", "description": "Hiring, layoffs, or leadership change signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "marketIntelligenceNews": { "type": "array", "description": "Event participation, recognition, and competitor activity signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "productActivityNews": { "type": "array", "description": "Product launch, development, and integration news signals", "items": { "$ref": "#/components/schemas/CompanyNewsSignal" } }, "surgeInHiring": { "type": "array", "description": "Overall hiring surge signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringSignal" } }, "surgeInHiringByDepartment": { "type": "array", "description": "Department-specific hiring signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByDepartmentSignal" } }, "surgeInHiringByLocation": { "type": "array", "description": "Location-specific hiring signals", "items": { "$ref": "#/components/schemas/CompanySurgeInHiringByLocationSignal" } }, "websiteTrafficIncrease": { "type": "array", "description": "Website traffic increase signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "websiteTrafficDecrease": { "type": "array", "description": "Website traffic decrease signals", "items": { "$ref": "#/components/schemas/CompanyWebsiteTrafficSignal" } }, "itSpendIncrease": { "type": "array", "description": "IT spending increase signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "itSpendDecrease": { "type": "array", "description": "IT spending decrease signals", "items": { "$ref": "#/components/schemas/CompanyItSpendSignal" } }, "headcountIncrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease1m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease3m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease6m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountIncrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } }, "headcountDecrease12m": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyHeadcountChangeSignal" } } } }, "CompanySignalsByIdResponse": { "type": "object", "properties": { "companies": { "type": "object", "description": "Map of company IDs to their signals", "additionalProperties": { "$ref": "#/components/schemas/CompanySignalData" } }, "endDate": { "type": "string", "format": "date", "description": "End date of the signal period", "example": "2025-07-31" }, "startDate": { "type": "string", "format": "date", "description": "Start date of the signal period", "example": "2025-01-01" }, "creditCharged": { "type": "integer", "description": "Number of credits charged for this request", "example": 3 } } }, "ContactLookalikesRequest": { "type": "object", "additionalProperties": false, "required": [ "seeds" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "description": "Dedupe session identifier. Omit on the first request to start a new run (server generates one). Provide on subsequent requests to get more results without duplicates.\n", "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, "description": "Number of results to return per call (1-100)", "example": 25 } } }, "ContactIdentifiersBatch": { "type": "object", "additionalProperties": false, "description": "Identifier batch for contact inputs. Provide at least one of linkedinUrls, contacts, emails, or contactIds. For seeds: total unique identifiers across all arrays must be 5-100. For exclude: total must be at most 500.\n", "properties": { "linkedinUrls": { "type": "array", "items": { "type": "string", "description": "LinkedIn profile URL" }, "maxItems": 100, "example": [ "https://www.linkedin.com/in/johndoe" ] }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactItem" }, "maxItems": 100 }, "emails": { "type": "array", "items": { "type": "string", "format": "email", "description": "Contact email" }, "maxItems": 100, "example": [ "john@acme.com" ] }, "contactIds": { "type": "array", "items": { "type": "integer", "description": "Lusha person ID" }, "maxItems": 100, "example": [ 1234, 4567 ] } }, "minProperties": 1, "nullable": true }, "ContactItem": { "type": "object", "additionalProperties": false, "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string", "description": "First name", "example": "John" }, "lastName": { "type": "string", "description": "Last name", "example": "Doe" }, "companyDomain": { "type": "string", "description": "Company domain (e.g., acme.com)", "example": "acme.com" }, "companyName": { "type": "string", "description": "Company name (alternative to companyDomain)", "example": "Acme Inc" } }, "description": "At least one of companyDomain or companyName is required." }, "ContactLookalikesResponse": { "type": "object", "additionalProperties": false, "required": [ "dedupeSessionId", "results", "meta" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Server-generated session id to use for subsequent \"get more\" requests. Null when no results on first request.\n", "example": "58adaa77-7a6e-4c9b-8c2d-820a6538e613" }, "results": { "type": "array", "description": "Lookalike contacts", "items": { "$ref": "#/components/schemas/LookalikeContactResult" } }, "meta": { "$ref": "#/components/schemas/ContactLookalikesMeta" }, "creditsCharged": { "type": "integer", "description": "Number of credits charged for this request", "example": 3, "minimum": 0 } } }, "LookalikeContactResult": { "type": "object", "additionalProperties": false, "properties": { "contactId": { "type": "string", "description": "Lusha person ID", "example": "9659196" }, "firstName": { "type": "string", "nullable": true, "description": "First name", "example": "Sarah" }, "lastName": { "type": "string", "nullable": true, "description": "Last name", "example": "Johnson" }, "socialLinks": { "type": "object", "properties": { "linkedin": { "type": "string", "nullable": true, "description": "LinkedIn profile URL", "example": "https://www.linkedin.com/in/sarahjohnson" } } }, "company": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID", "example": "8605368" }, "name": { "type": "string", "nullable": true, "description": "Company name", "example": "Marriott International" }, "domain": { "type": "string", "nullable": true, "description": "Company domain", "example": "marriott.com" } } }, "jobTitle": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "description": "Job title", "example": "VP of Sales" }, "departments": { "type": "array", "items": { "type": "string" }, "description": "Departments", "example": [ "Sales" ] }, "seniority": { "type": "string", "nullable": true, "description": "Seniority level", "example": "Director" } } }, "location": { "$ref": "#/components/schemas/ContactLocation" } } }, "ContactLocation": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "string", "nullable": true, "example": "United States" }, "state": { "type": "string", "nullable": true, "example": "Maryland" }, "city": { "type": "string", "nullable": true, "example": "Bethesda" } } }, "ContactLookalikesMeta": { "type": "object", "additionalProperties": false, "required": [ "returned", "hasMore" ], "properties": { "returned": { "type": "integer", "description": "Number of results returned in this response", "example": 25 }, "hasMore": { "type": "boolean", "description": "Indicates whether more results are available for the same seeds + dedupeSessionId", "example": true } } }, "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." } } }, "CompanyIdentifiersBatch": { "type": "object", "description": "Identifier batch for company inputs. Provide at least one of domains/linkedinUrls. For seeds: total unique identifiers across both arrays must be 5-100.\n", "properties": { "domains": { "type": "array", "items": { "type": "string", "description": "Company domain (e.g., \"sap.com\")" }, "maxItems": 100, "example": [ "sap.com", "oracle.com" ] }, "linkedinUrls": { "type": "array", "items": { "type": "string", "description": "LinkedIn company URL" }, "maxItems": 100, "example": [ "https://www.linkedin.com/company/sap" ] } }, "minProperties": 1 }, "CompanyLookalikesRequest": { "type": "object", "required": [ "seeds" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "description": "Dedupe session identifier. Omit on the first request to start a new run (server generates one). Provide on subsequent requests to get more results without duplicates.\n", "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, "description": "Number of results to return per call (1-100)", "example": 25 } } }, "LookalikeCompanyResult": { "type": "object", "required": [ "domain", "linkedinUrl", "name", "employeeCount", "industry", "location" ], "properties": { "domain": { "type": "string", "nullable": true, "description": "Company domain", "example": "marriott.com" }, "linkedinUrl": { "type": "string", "nullable": true, "description": "LinkedIn company URL", "example": "https://www.linkedin.com/company/marriott-international" }, "name": { "type": "string", "description": "Company name", "example": "Marriott International" }, "employeeCount": { "type": "integer", "nullable": true, "description": "Employee count (best available)", "example": 255334 }, "industry": { "type": "string", "nullable": true, "description": "Industry name/category", "example": "Hospitality" }, "location": { "type": "object", "required": [ "country", "state", "city" ], "properties": { "country": { "type": "string", "nullable": true, "example": "United States" }, "state": { "type": "string", "nullable": true, "example": "Maryland" }, "city": { "type": "string", "nullable": true, "example": "Bethesda" } } } } }, "CompanyLookalikesMeta": { "type": "object", "required": [ "returned", "hasMore" ], "properties": { "returned": { "type": "integer", "description": "Number of results returned in this response", "example": 1 }, "hasMore": { "type": "boolean", "description": "Indicates whether more results are available for the same seeds + dedupeSessionId", "example": true } } }, "CompanyLookalikesResponse": { "type": "object", "required": [ "dedupeSessionId", "results", "meta" ], "properties": { "dedupeSessionId": { "type": "string", "format": "uuid", "description": "Server-generated session id to use for subsequent \"get more\" requests", "example": "58adaa77-7a6e-4c9b-8c2d-820a6538e613" }, "results": { "type": "array", "description": "Lookalike companies", "items": { "$ref": "#/components/schemas/LookalikeCompanyResult" } }, "meta": { "$ref": "#/components/schemas/CompanyLookalikesMeta" }, "creditsCharged": { "type": "integer", "description": "Number of credits charged for this request", "example": 3, "minimum": 0 } } }, "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. Available signals depend on entity type:\n\n**Examples for contacts:**\n- `promotion` - Job title promotions\n- `companyChange` - Company changes\n- `allSignals` - All contact signals\n\n**Examples for companies:**\n- `financialEventsNews` - Funding Round, Asset Investment, Strategic Investment, IPO\n- `allSignals` - All company signals\n- `surgeInHiring` - Overall hiring activity increase\n\nPlease refer to the [**Signal Options Section**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions) for a full list of available signals.\n" } }, "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 10 in development, 25 in production)", "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", "description": "Total number of subscription creation attempts", "example": 3 }, "successful": { "type": "integer", "description": "Number of successfully created subscriptions", "example": 2 }, "failed": { "type": "integer", "description": "Number of failed subscription attempts", "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", "description": "Index of the subscription in the request array", "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", "description": "Index of the subscription in the request array", "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", "description": "Total number of deletion attempts", "example": 3 }, "successful": { "type": "integer", "description": "Number of successfully deleted subscriptions", "example": 2 }, "failed": { "type": "integer", "description": "Number of failed deletion attempts", "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", "description": "Index of the subscription in the request array", "example": 0 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "subscription": { "type": "object", "description": "Information about the deleted subscription", "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", "description": "Index of the subscription in the request array", "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", "description": "Subscription ID", "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 for signature verification (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" } } }, "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" ], "description": "Type of entity", "example": "contact" }, "entityId": { "type": "string", "description": "ID of the entity (contact or company)", "example": "4158887495" }, "subscriptionId": { "type": "string", "description": "Subscription ID that triggered this webhook", "example": "507f1f77bcf86cd799439011" }, "data": { "type": "object", "description": "Signal-specific payload data in camelCase format.\nStructure varies by signal type.\n", "example": { "personId": 4158887495, "currentCompanyId": 40823133, "currentCompanyName": "OMG Hospitality Group LLC", "currentDomain": "omghospitalitygroup.com", "currentTitle": "Bartender", "currentDepartments": [ { "id": 7, "value": "Other" } ], "previousCompanyName": "First Watch Restaurants", "previousDomain": "firstwatch.com", "signalDate": "2025-07-01" } }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the signal was generated", "example": "2026-01-14T16:16:35.841Z" }, "billing": { "type": "object", "required": [ "creditsCharged" ], "properties": { "creditsCharged": { "type": "integer", "description": "Number of credits charged for this delivery", "example": 1 } } } } }, "AuditLogEntry": { "type": "object", "required": [ "id", "subscriptionId", "payloadId", "status", "url", "deliveredAt" ], "properties": { "id": { "type": "string", "description": "Audit log entry ID", "example": "log-123" }, "subscriptionId": { "type": "string", "description": "Subscription ID", "example": "sub-123" }, "payloadId": { "type": "string", "description": "Unique payload ID", "example": "payload-456" }, "status": { "type": "string", "enum": [ "success", "failed", "permanent_failure" ], "description": "Delivery status", "example": "success" }, "statusCode": { "type": "integer", "description": "HTTP status code from webhook endpoint", "example": 200 }, "url": { "type": "string", "format": "uri", "description": "Webhook URL that was called", "example": "https://example.com/webhook" }, "deliveredAt": { "type": "string", "format": "date-time", "description": "When the webhook was delivered", "example": "2024-01-01T00:00:00.000Z" }, "durationMs": { "type": "integer", "description": "Delivery duration in milliseconds", "example": 150 }, "error": { "type": "string", "nullable": true, "description": "Error message if delivery failed", "example": null } } }, "PaginationResponse": { "type": "object", "required": [ "total", "limit", "offset", "hasMore" ], "properties": { "total": { "type": "integer", "description": "Total number of results", "example": 100 }, "limit": { "type": "integer", "description": "Maximum results per page", "example": 50 }, "offset": { "type": "integer", "description": "Number of results skipped", "example": 0 }, "hasMore": { "type": "boolean", "description": "Whether more results are available", "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", "description": "Total number of delivery attempts", "example": 1000 }, "success": { "type": "integer", "description": "Number of successful deliveries", "example": 950 }, "failed": { "type": "integer", "description": "Number of failed deliveries", "example": 50 }, "successRate": { "type": "string", "description": "Success rate as percentage", "example": "95.00%" } } }, "SubscriptionListResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionWithoutSecret" } }, "pagination": { "$ref": "#/components/schemas/PaginationResponse" } } }, "TestSubscriptionResponse": { "type": "object", "required": [ "subscriptionId", "url", "mode", "isSuccess", "timestamp" ], "properties": { "subscriptionId": { "type": "string", "description": "Subscription ID that was tested", "example": "507f1f77bcf86cd799439011" }, "subscriptionName": { "type": "string", "description": "Name of the subscription", "example": "My Test Webhook" }, "url": { "type": "string", "format": "uri", "description": "Webhook URL that was tested", "example": "https://example.com/webhook" }, "mode": { "type": "string", "enum": [ "direct", "kafka", "full" ], "description": "Test mode used", "example": "full" }, "flowCheck": { "type": "object", "description": "Results of the test", "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer", "example": 200 }, "durationMs": { "type": "integer", "example": 150 } } }, "testPayload": { "type": "object", "description": "Test payload that was sent", "properties": { "entityType": { "type": "string", "example": "contact" }, "signalType": { "type": "string", "example": "promotion" }, "data": { "type": "object" } } }, "isSuccess": { "type": "boolean", "description": "Overall test success", "example": true }, "timestamp": { "type": "string", "format": "date-time", "description": "When the test was executed", "example": "2024-01-01T00:00:00.000Z" } } }, "CompanyLocationFilter2": { "type": "object", "description": "Site-level office location filter. At least `country` is required.\n`state` without `country` is not supported.\n", "required": [ "country" ], "properties": { "country": { "type": "string", "example": "United States" }, "state": { "type": "string", "example": "California" } } }, "EmployeesInLinkedInFilter": { "type": "object", "description": "Filter companies by LinkedIn-reported employee count.\nBoth `min` and `max` are optional — provide either or both.\n", "properties": { "min": { "type": "integer", "format": "int64", "description": "Minimum employee count (inclusive)", "example": 100 }, "max": { "type": "integer", "format": "int64", "description": "Maximum employee count (inclusive)", "example": 5000 } } } } } }