> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Subscription (Legacy)
> Creates one or more webhook subscriptions for real-time signal notifications.
**Delivery & Reliability:**
- Webhooks are delivered with automatic retry on failures
- Maximum 3 retry attempts with exponential backoff
- Subscriptions auto-disable after max retries exceeded
- All deliveries are logged in audit logs
> **Note:** Your webhook endpoint must respond with a proper acknowledgment.
See Client Response Format below for details.
> **Limit:** Maximum 25 subscriptions per request
*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions**
---
### Webhook Payload You'll Receive
When a signal is triggered, this payload is sent to your webhook URL:
```json
{
"id": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c",
"type": "promotion",
"entityType": "contact",
"entityId": "4158887495",
"subscriptionId": "507f1f77bcf86cd799439011",
"data": {
"personId": 4158887495,
"currentCompanyId": 40823133,
"currentCompanyName": "OMG Hospitality Group LLC",
"currentDomain": "omghospitalitygroup.com",
"currentTitle": "Bartender",
"currentDepartments": [
{ "id": 7, "value": "Other" }
],
"previousCompanyName": "First Watch Restaurants",
"previousDomain": "firstwatch.com",
"signalDate": "2025-07-01"
},
"timestamp": "2026-01-14T16:16:35.841Z",
"billing": {
"creditsCharged": 1
}
}
```
**Example — Company News Signal:**
```json
{
"id": "a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45",
"type": "commercialActivityNews",
"entityType": "company",
"entityId": "33222678",
"subscriptionId": "507f1f77bcf86cd799439011",
"data": {
"companyId": "33222678",
"companyName": "Lusha",
"domain": "lusha.com",
"signalId": "1503910",
"eventType": "partnership",
"eventSummary": "Lusha announced a strategic partnership with Salesforce.",
"articlePublishedDate": "2025-06-15",
"articleTitle": "Lusha Partners with Salesforce",
"articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.",
"eventEffectiveDate": "2025-06-10",
"articleUrl": "https://example.com/lusha-salesforce-partnership"
},
"timestamp": "2026-01-14T16:16:35.841Z",
"billing": {
"creditsCharged": 1
}
}
```
**Headers Included:**
| Header | Description |
|--------|-------------|
| `X-Lusha-Signature` | HMAC-SHA256 signature for verification |
| `X-Lusha-Timestamp` | Unix timestamp of the request |
| `Content-Type` | application/json |
| `User-Agent` | Lusha-Webhooks/1.0 |
---
⚠️ **Important:** Ensure your account has a webhook secret before creating subscriptions.
Create one via the [Regenerate Account Secret](#operation/regenerateAccountSecret) endpoint.
---
### Client Response Format (Required)
When your webhook endpoint receives a delivery, it **must** acknowledge receipt with this response:
**Required Response:**
````json
{
"received": true,
"timestamp": "2026-02-05T10:30:45.123Z",
"webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c"
}
````
Response Requirements
| Requirement | Value |
|-------------|-------|
| **HTTP Status** | `201 Created` (recommended) or any `2xx` status |
| **Content-Type** | `application/json` |
| **Response Time** | Within 10 seconds |
Field Descriptions & Implementation Guide
**Field Descriptions:**
* `received` (boolean, required): Confirmation flag - must be `true`
* `timestamp` (string, required): ISO 8601 timestamp of receipt
* `webhookId` (string, required): Echo the `id` from webhook payload
**Implementation Example:**
```javascript
app.post('/webhook', async (req, res) => {
// 1. Verify signature
if (!verifyWebhookSignature(req)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 2. Queue for async processing
await queueWebhook(req.body);
// 3. Acknowledge immediately
res.status(201).json({
received: true,
timestamp: new Date().toISOString(),
webhookId: req.body.id
});
```
**Important Notes:**
* Return acknowledgment **before** heavy processing
* Non-2xx responses trigger retry mechanism
* After 3 failed retries, subscription is disabled
----
## OpenAPI
````yaml /v2/openapi.json post /api/subscriptions
openapi: 3.0.3
info:
title: Lusha API Documentation
version: 0.0.1
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.
It 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.
Use the Lusha API to search for new prospects, enrich existing records,
react to real-world changes, and expand coverage using lookalike
recommendations.
*All API requests should be made over HTTPS (SSL), and the response bodies
are delivered in JSON format.*
---
---
**Data Source and Privacy**
Please 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.
For more information on how we collect, use, and handle business profiles,
please refer to our [Privacy
Policy](https://lusha.com/legal/privacy-notice/).
----
## Authentication
API 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.
How
to Authenticate:
When making an API call, include your API key in the `api_key` header of the
request.
> You can generate and retrieve your API key
[here](https://dashboard.lusha.com/api/manage-api-keys).
API keys should be stored securely and used only in server-side
environments.
---
### Rate Limiting
Lusha API enforces rate limiting to ensure fair usage and protect against
excessive load.
- **General Rate Limit**: You can make up to 25 requests per second to each
API endpoint
- **Credit Usage API**: Has a specific rate limit of 5 requests per minute
> **Note**: Rate limits may vary based on your account type and subscription
plan.
If you're encountering rate limit issues frequently, please consult with your
account manager or Lusha support team to discuss your specific needs.
**Rate Limit Headers**
To monitor your current rate limit status, check the HTTP response headers
in your API calls:
| Header | Description |
|--------|-------------|
| `x-rate-limit-daily` | The total number of requests allowed per day under
your current plan |
| `x-daily-requests-left` | The number of requests remaining in your daily
quota |
| `x-daily-usage` | The number of requests you have made in the current
daily period |
| `x-rate-limit-hourly` | The total number of requests allowed per hour
under your current plan |
| `x-hourly-requests-left` | The number of requests remaining in your hourly
quota |
| `x-hourly-usage` | The number of requests you have made in the current
hourly period |
| `x-rate-limit-minute` | The total number of requests allowed per minute
under your current plan |
| `x-minute-requests-left` | The number of requests remaining in your
current minute window |
| `x-minute-usage` | The number of requests you have made in the current
minute window |
**Notes on API Rate Limiting**
- If you exceed the rate limit, the API will return a 429 (Too Many
Requests) error.
- To ensure a smooth experience, respect the rate limits defined by your
subscription tier.
- Daily limits vary based on your billing plan — higher tiers have higher
quotas.
- You can programmatically track your usage through these response headers:
- `X-RateLimit-Remaining-Daily`
- `X-RateLimit-Reset-Daily`
- It is strongly recommended to implement logic that:
- Monitors these headers
- Pauses or retries requests accordingly
- Helps avoid hitting the limit and ensures reliable operation
---
## Error Codes
Lusha 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.
| Status Code | Name | Description |
|-------------|------|-------------|
| **200** | OK | Successful request |
| **400** | Bad Request | Badly formatted request |
| **401** | Unauthorized | The API key is invalid |
| **402** | Payment Required | Your account requires payment |
| **403** | Forbidden | Your account is not active. Please reach out to
support at *support@lusha.com* for assistance |
| **403** | Forbidden | Your pricing version does not support requesting
individual datapoints [revealEmails, revealPhones] |
| **404** | Not Found | The requested endpoint was not found |
| **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 |
| **429** | Too Many Requests | You've reached your trial limit, please
contact support for upgrade |
| **429** | Too Many Requests | Daily API quota limit exceeded. Limit X
calls per day |
| **429** | Too Many Requests | Hourly API rate limit exceeded. Limit: X
calls per hour. Reset in X seconds |
| **451** | Unavailable For Legal Reasons | We are unable to process this
contact request due to our GDPR regulations |
| **499** | Client Closed Request | Request failed due to request timeout |
| **5XX** | Server Error | There's a problem on Lusha's end |
**Error Response Format**
In case of an error, the response body will contain details about the error:
```json
{
"error": {
"code": 400,
"message": "Invalid request parameters"
}
}
```
Handling errors
- Always ensure your API key is correct and valid
- Pay attention to the specific error message and code to troubleshoot
issues efficiently
- Implement proper error handling and retry logic in your application
- For 5XX errors, implement exponential backoff before retrying
---
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?**:
Enrichment is the process of adding missing or updated data to existing
contact or company records.
Use enrichment to:
- Complete CRM records
- Improve outbound accuracy and deliverability
- Keep records current as people and companies change
> Enrichment can be performed in real time or in bulk, depending on the
endpoint and use case.
**Available enrichment APIs**
Person enrichment:
- [**Search single
contact**](/apis/openapi/enrichment/searchsinglecontact) - Enrich one
contact at a time
- [**Search multiple
contacts**](/apis/openapi/enrichment/searchmultiplecontacts) - Bulk enrich
contacts
Company enrichment:
- [**Search a single
company**](/apis/openapi/enrichment/searchsinglecompanyv2) - Enrich one
company at a time
- [**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.
The 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).
This process involves three main steps:
| Step | API | Description |
|------|-----|-------------|
| 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)*|
| 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 |
| 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 |
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.
[**Contact Lookalikes**](/apis/openapi/lookalikes/getcontactlookalikes) -
Find similar contacts based on role, seniority, and industry patterns.
[**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.
Webhooks deliver HTTP POST requests to your endpoints when signals occur -
from promotions and job changes to company growth.
> For a full list of available signals, refer to [**Signal
Options**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions).
---
**Key Features:**
- Real-time contact & company signal notifications
- Bulk subscription management (up to 25 items per request)
- Secure delivery with HMAC-SHA256 signatures
- Delivery monitoring with audit logs
**Available Endpoints:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/subscriptions` | Create subscriptions (bulk supported) |
| GET | `/api/subscriptions` | List all subscriptions |
| GET | `/api/subscriptions/{id}` | Get subscription by ID |
| PATCH | `/api/subscriptions/{id}` | Update subscription |
| POST | `/api/subscriptions/delete` | Delete subscriptions (bulk
supported) |
| POST | `/api/subscriptions/{id}/test` | Test subscription delivery |
| GET | `/api/audit-logs` | Get webhook delivery logs |
| GET | `/api/audit-logs/stats` | Get delivery statistics |
| GET | `/api/account/secret` | Get account webhook secret |
| POST | `/api/account/secret/regenerate` | Regenerate account secret |
> **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.
---
Rate Limits
| Operation | Limit |
|-----------|-------|
| API Requests | 100 requests/minute per account |
| Create Subscriptions | 25 items per request |
| Delete Subscriptions | 25 items per request |
---
Security & Verification
**HTTPS Requirement:**
- Production webhook URLs **must** use HTTPS
- HTTP URLs are not accepted
**Signature Verification:**
All webhook deliveries include an `X-Lusha-Signature` header containing an
HMAC-SHA256 signature. Verify this signature to ensure the request is from
Lusha:
1. Extract the `X-Lusha-Signature` and `X-Lusha-Timestamp` headers
2. Concatenate: `timestamp + "." + JSON.stringify(payload)`
3. Compute HMAC-SHA256 using your webhook secret
4. Compare the computed signature with the received signature
**Example (Node.js):**
```javascript
const crypto = require('crypto');
function verifySignature(payload, signature, timestamp, secret) {
const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
```
> **Security Best Practice:** Always verify webhook signatures to prevent
spoofed requests.
---
Credits & Billing
**Credit Charges:**
- Credits are charged when signals are detected and delivered to your
webhook
- The `creditsCharged` field in the webhook payload indicates how many
credits were used
- Credits are deducted from your account balance per signal type
**No Duplicate Charges:**
- Each signal is delivered once and charged once
- Webhook delivery retries do not incur additional charges
---
Error Response Format
All error responses follow this format:
```json
{
"statusCode": 400,
"message": "Validation failed",
"errors": ["entityType must be one of: contact, company"]
}
```
| Field | Type | Description |
|-------|------|-------------|
| `statusCode` | number | HTTP status code |
| `message` | string | Error message |
| `errors` | string[] | Detailed error messages (optional) |
---
- name: Account Management
description: >
Manage your account and monitor usage.
Use this endpoint to:
- Monitor credit usage
- Understand consumption patterns
- Align API usage with plan limits
- Support governance and production operations
Account-level insights are especially important for teams running Lusha at
scale or across multiple systems.
paths:
/api/subscriptions:
post:
tags:
- Webhooks
summary: Create Subscription (Legacy)
description: >
Creates one or more webhook subscriptions for real-time signal
notifications.
**Delivery & Reliability:**
- Webhooks are delivered with automatic retry on failures
- Maximum 3 retry attempts with exponential backoff
- Subscriptions auto-disable after max retries exceeded
- All deliveries are logged in audit logs
> **Note:** Your webhook endpoint must respond with a proper
acknowledgment.
See Client Response Format below for details.
> **Limit:** Maximum 25 subscriptions per request
*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions**
---
### Webhook Payload You'll Receive
When a signal is triggered, this payload is sent to your webhook URL:
```json
{
"id": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c",
"type": "promotion",
"entityType": "contact",
"entityId": "4158887495",
"subscriptionId": "507f1f77bcf86cd799439011",
"data": {
"personId": 4158887495,
"currentCompanyId": 40823133,
"currentCompanyName": "OMG Hospitality Group LLC",
"currentDomain": "omghospitalitygroup.com",
"currentTitle": "Bartender",
"currentDepartments": [
{ "id": 7, "value": "Other" }
],
"previousCompanyName": "First Watch Restaurants",
"previousDomain": "firstwatch.com",
"signalDate": "2025-07-01"
},
"timestamp": "2026-01-14T16:16:35.841Z",
"billing": {
"creditsCharged": 1
}
}
```
**Example — Company News Signal:**
```json
{
"id": "a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45",
"type": "commercialActivityNews",
"entityType": "company",
"entityId": "33222678",
"subscriptionId": "507f1f77bcf86cd799439011",
"data": {
"companyId": "33222678",
"companyName": "Lusha",
"domain": "lusha.com",
"signalId": "1503910",
"eventType": "partnership",
"eventSummary": "Lusha announced a strategic partnership with Salesforce.",
"articlePublishedDate": "2025-06-15",
"articleTitle": "Lusha Partners with Salesforce",
"articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.",
"eventEffectiveDate": "2025-06-10",
"articleUrl": "https://example.com/lusha-salesforce-partnership"
},
"timestamp": "2026-01-14T16:16:35.841Z",
"billing": {
"creditsCharged": 1
}
}
```
**Headers Included:**
| Header | Description |
|--------|-------------|
| `X-Lusha-Signature` | HMAC-SHA256 signature for verification |
| `X-Lusha-Timestamp` | Unix timestamp of the request |
| `Content-Type` | application/json |
| `User-Agent` | Lusha-Webhooks/1.0 |
---
⚠️ **Important:** Ensure your account has a webhook secret before
creating subscriptions.
Create one via the [Regenerate Account
Secret](#operation/regenerateAccountSecret) endpoint.
---
### Client Response Format (Required)
When your webhook endpoint receives a delivery, it **must** acknowledge
receipt with this response:
**Required Response:**
````json
{
"received": true,
"timestamp": "2026-02-05T10:30:45.123Z",
"webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c"
}
````
Response Requirements
| Requirement | Value |
|-------------|-------|
| **HTTP Status** | `201 Created` (recommended) or any `2xx` status |
| **Content-Type** | `application/json` |
| **Response Time** | Within 10 seconds |
Field Descriptions & Implementation
Guide
**Field Descriptions:**
* `received` (boolean, required): Confirmation flag - must be `true`
* `timestamp` (string, required): ISO 8601 timestamp of receipt
* `webhookId` (string, required): Echo the `id` from webhook payload
**Implementation Example:**
```javascript
app.post('/webhook', async (req, res) => {
// 1. Verify signature
if (!verifyWebhookSignature(req)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 2. Queue for async processing
await queueWebhook(req.body);
// 3. Acknowledge immediately
res.status(201).json({
received: true,
timestamp: new Date().toISOString(),
webhookId: req.body.id
});
```
**Important Notes:**
* Return acknowledgment **before** heavy processing
* Non-2xx responses trigger retry mechanism
* After 3 failed retries, subscription is disabled
----
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'
components:
schemas:
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:
**Examples for contacts:**
- `promotion` - Job title promotions
- `companyChange` - Company changes
- `allSignals` - All contact signals
**Examples for companies:**
- `financialEventsNews` - Funding Round, Asset Investment,
Strategic Investment, IPO
- `allSignals` - All company signals
- `surgeInHiring` - Overall hiring activity increase
Please refer to the [**Signal Options
Section**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions)
for a full list of available signals.
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'
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'
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'
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'
responses:
Unauthorized:
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 401
message: Invalid API key
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 500
message: Internal server error. Please try again later.
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.
Include this key in the `api_key` header for all requests.
````
## Related topics
- [Update Subscription (Legacy)](https://docs.lusha.com/api-reference/webhooks/update-subscription-legacy.md)
- [Delete Subscriptions (Legacy)](https://docs.lusha.com/api-reference/webhooks/delete-subscriptions-legacy.md)
- [List Subscriptions (Legacy)](https://docs.lusha.com/api-reference/webhooks/list-subscriptions-legacy.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.