### Webhook Payload Examples

Source: https://docs.lusha.com/apis/openapi

Examples of webhook payloads that Lusha sends when a signal is triggered. These payloads contain information about the event and the associated entity.

```APIDOC
## Webhook Payload Examples

### Promotion Signal Payload

This payload is sent when a promotion signal is triggered:

```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
  }
}
```

### Company News Signal Payload

This payload is sent for company news signals:

```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
  }
}
```
```

--------------------------------

### Webhook Implementation Example - Node.js

Source: https://docs.lusha.com/apis/openapi/webhooks/createsubscription

This JavaScript example demonstrates how to handle incoming webhook deliveries. It includes signature verification, queuing for asynchronous processing, and sending the required acknowledgment response.

```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
  });
  

```

--------------------------------

### Webhook Payload Examples

Source: https://docs.lusha.com/apis/openapi.md

This section provides examples of the JSON payloads you will receive when a signal is triggered. It includes a 'promotion' type for contacts and a 'commercialActivityNews' type for companies.

```APIDOC
## Webhook Payload Examples

### Promotion Signal Payload

```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
  }
}
```

### Company News Signal Payload

```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 |
```

--------------------------------

### Webhook Payload Example - Company News Signal

Source: https://docs.lusha.com/apis/openapi/webhooks/createsubscription

This example demonstrates the webhook payload structure for a company news signal. It contains information about company-related news events, such as partnerships or other commercial activities.

```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
  }
}
```

--------------------------------

### Webhook Payload Example - Contact Promotion

Source: https://docs.lusha.com/apis/openapi/webhooks/createsubscription

This is an example of the webhook payload received when a contact promotion signal is triggered. It includes details about the entity, subscription, and specific data related to the promotion.

```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
  }
}
```

--------------------------------

### GET /v3/companies/signals/types

Source: https://docs.lusha.com/apis/openapi/signals

Returns the full list of supported signal types for companies.

```APIDOC
## GET /v3/companies/signals/types

### Description
Returns the full list of supported signal types for companies.

### Method
GET

### Endpoint
/v3/companies/signals/types

### Response
#### Success Response (200)
- **signalTypes** (array of strings) - A list of supported signal types for companies (e.g., `headcountIncrease1m`, `websiteTrafficIncrease`, `riskNews`, `allSignals`).

#### Response Example
```json
{
  "signalTypes": [
    "headcountIncrease1m",
    "headcountIncrease3m",
    "headcountIncrease6m",
    "headcountIncrease12m",
    "headcountDecrease1m",
    "headcountDecrease3m",
    "headcountDecrease6m",
    "headcountDecrease12m",
    "surgeInHiring",
    "surgeInHiringByDepartment",
    "surgeInHiringByLocation",
    "websiteTrafficIncrease",
    "websiteTrafficDecrease",
    "itSpendIncrease",
    "itSpendDecrease",
    "riskNews",
    "commercialActivityNews",
    "corporateStrategyNews",
    "financialEventsNews",
    "peopleNews",
    "marketIntelligenceNews",
    "productActivityNews",
    "allSignals"
  ]
}
```
```

--------------------------------

### Forbidden Response Example (403)

Source: https://docs.lusha.com/apis/openapi/webhooks/createoptoutsubscription

A 403 response indicates that the authenticated user does not have permission to perform the requested action.

```json
{
  "statusCode": 403,
  "message": "Validation failed",
  "errors": ["entityType must be one of: contact, company"]
}
```

--------------------------------

### Get Account Usage

Source: https://docs.lusha.com/apis/openapi/account

Returns a full snapshot of your account status, including credits, rate limits, plan details, and pricing.

```APIDOC
## GET /v3/account/usage

### Description
Returns a full snapshot of your account status: Credits (total, used, and remaining for the current billing cycle), Rate limits (current usage and reset times for daily, hourly, and per-minute windows), Plan (your current plan category and renewal dates), and Pricing (credit cost per action type across all public API endpoints).

### Method
GET

### Endpoint
/v3/account/usage

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **credits** (object) - Total, used, and remaining credits for the current billing cycle.
- **rate_limits** (object) - Current usage and reset times for daily, hourly, and per-minute windows.
- **plan** (object) - Your current plan category and renewal dates.
- **pricing** (object) - Credit cost per action type across all public API endpoints.
```

--------------------------------

### Account

Source: https://docs.lusha.com/apis/openapi/section/available-endpoints

Usage, credits, rate limits, and pricing.

```APIDOC
## Account

### Description
Usage, credits, rate limits, and pricing.

### Method
GET, POST (specific methods depend on implementation)

### Endpoint
/account

### Parameters
(Specific parameters not detailed in the source text)

### Request Example
(Not provided in the source text)

### Response
(Specific response details not provided in the source text)
```

--------------------------------

### GET /v3/contacts/signals/types

Source: https://docs.lusha.com/apis/openapi/signals

Returns the full list of supported signal types for contacts.

```APIDOC
## GET /v3/contacts/signals/types

### Description
Returns the full list of supported signal types for contacts.

### Method
GET

### Endpoint
/v3/contacts/signals/types

### Response
#### Success Response (200)
- **signalTypes** (array of strings) - A list of supported signal types for contacts (e.g., `promotion`, `companyChange`, `allSignals`).

#### Response Example
```json
{
  "signalTypes": [
    "promotion",
    "companyChange",
    "allSignals"
  ]
}
```
```

--------------------------------

### GET /v3/companies/prospecting/filters/{filterType}

Source: https://docs.lusha.com/apis/openapi

Returns valid values for a single company filter type.

```APIDOC
## GET /v3/companies/prospecting/filters/{filterType}

### Description
Returns valid values for a single company filter type.

### Method
GET

### Endpoint
/v3/companies/prospecting/filters/{filterType}

### Parameters
#### Path Parameters
- **filterType** (string) - Required - The type of filter for which to retrieve valid values.
```

--------------------------------

### Create Subscriptions

Source: https://docs.lusha.com/apis/openapi/signals/getsignaloptions

Allows users to create new webhook subscriptions, supporting bulk creation of up to 25 items per request. Your endpoint must acknowledge receipt with a specific format.

```APIDOC
## POST /api/subscriptions

### Description
Create subscriptions (bulk supported).

### Method
POST

### Endpoint
/api/subscriptions

### Parameters
#### Request Body
- **items** (array) - Required - List of subscriptions to create. Each item should define the signal type, entity type, and the webhook URL.

### Request Example
{
  "items": [
    {
      "signalType": "job_change",
      "entityType": "contact",
      "webhookUrl": "https://your-webhook-url.com/callback"
    }
  ]
}

### Response
#### Success Response (200)
- **subscriptions** (array) - Details of the created subscriptions.

#### Response Example
{
  "subscriptions": [
    {
      "id": "sub_12345",
      "signalType": "job_change",
      "entityType": "contact",
      "webhookUrl": "https://your-webhook-url.com/callback",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### GET /v3/contacts/prospecting/filters/{filterType}

Source: https://docs.lusha.com/apis/openapi

Returns valid values for a single contact filter type.

```APIDOC
## GET /v3/contacts/prospecting/filters/{filterType}

### Description
Returns valid values for a single contact filter type.

### Method
GET

### Endpoint
/v3/contacts/prospecting/filters/{filterType}

### Parameters
#### Path Parameters
- **filterType** (string) - Required - The type of filter for which to retrieve valid values.
```

--------------------------------

### Get Account Usage

Source: https://docs.lusha.com/apis/openapi/account/getaccountusage

Fetches a full snapshot of your account status, including credits, rate limits, plan details, and pricing. This endpoint is limited to 5 requests per minute.

```APIDOC
## GET /v3/account/usage

### Description
Returns a full snapshot of your account status: Credits (total, used, and remaining), Rate limits (current usage and reset times), Plan (current plan category and renewal dates), and Pricing (credit cost per action type).

### Method
GET

### Endpoint
/v3/account/usage

### Security
ApiKeyAuth

### Rate Limiting
This endpoint is limited to 5 requests per minute.

### Response
#### Success Response (200)
- **credits** (object)
  - **credits.total** (number) - Example: 10000
  - **credits.used** (number) - Example: 1500
  - **credits.remaining** (number) - Example: 8500
- **rateLimits** (object, null)
  - **rateLimits.daily** (object, null)
    - **rateLimits.daily.limit** (number) - Example: 5000
    - **rateLimits.daily.resetsAt** (string) - Example: "2026-03-31T00:00:00.000Z"
  - **rateLimits.hourly** (object, null)
  - **rateLimits.minute** (object, null)
- **plan** (object)
  - **plan.category** (string) - Example: "professional"
  - **plan.renewalType** (string) - Example: "annual"
  - **plan.startDate** (string) - Example: "2026-01-01T00:00:00.000Z"
  - **plan.endDate** (string) - Example: "2027-01-01T00:00:00.000Z"
- **pricing** (object)

#### Response Example (200)
{
  "credits": {
    "total": 10000,
    "used": 1500,
    "remaining": 8500
  },
  "rateLimits": {
    "daily": {
      "limit": 5000,
      "resetsAt": "2026-03-31T00:00:00.000Z"
    },
    "hourly": null,
    "minute": null
  },
  "plan": {
    "category": "professional",
    "renewalType": "annual",
    "startDate": "2026-01-01T00:00:00.000Z",
    "endDate": "2027-01-01T00:00:00.000Z"
  },
  "pricing": {}
}

#### Error Response (401, 403, 429, 500)
- **statusCode** (integer, required) - HTTP status code
- **message** (string, required) - Error message
- **errors** (array, optional) - Detailed error messages
```

--------------------------------

### Get Audit Log Statistics

Source: https://docs.lusha.com/apis/openapi/webhooks

Retrieves delivery statistics for your account's webhooks.

```APIDOC
## Get Audit Log Statistics

### Description
Get delivery statistics for your account's webhooks. This endpoint provides aggregated data on webhook delivery performance.

### Method
GET

### Endpoint
/api/audit-logs/stats

### Response
#### Success Response (200)
- **totalDeliveries** (integer) - Total number of webhook deliveries.
- **successfulDeliveries** (integer) - Number of successful webhook deliveries.
- **failedDeliveries** (integer) - Number of failed webhook deliveries.
- **averageResponseTime** (number) - Average response time in milliseconds.

#### Response Example
```json
{
  "totalDeliveries": 1000,
  "successfulDeliveries": 950,
  "failedDeliveries": 50,
  "averageResponseTime": 200
}
```
```

--------------------------------

### Create Opt-Out Subscription Request

Source: https://docs.lusha.com/apis/openapi/webhooks/createoptoutsubscription

Use this request to create a new opt-out subscription. Ensure your account has a webhook secret before proceeding. The 'entityType' must be 'contact' and a valid HTTPS 'url' is required.

```bash
curl -X POST \
  https://api.lusha.com/api/subscriptions/opt-out \
  -H 'Authorization: ApiKey YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ 
    "entityType": "contact", 
    "url": "https://example.com/webhook", 
    "name": "Account opt-out webhook" 
  }'
```

--------------------------------

### GET /api/audit-logs/stats

Source: https://docs.lusha.com/apis/openapi/webhooks

Retrieves statistics about webhook delivery performance, including success and failure rates.

```APIDOC
## GET /api/audit-logs/stats

### Description
Retrieves statistics about webhook delivery performance, including success and failure rates.

### Method
GET

### Endpoint
/api/audit-logs/stats

### Parameters
#### Query Parameters
- **startDate** (string) - Optional - Filter statistics from this date (YYYY-MM-DD).
- **endDate** (string) - Optional - Filter statistics up to this date (YYYY-MM-DD).

### Response
#### Success Response (200)
- **totalDeliveries** (integer) - The total number of webhook deliveries attempted.
- **successfulDeliveries** (integer) - The number of successful webhook deliveries.
- **failedDeliveries** (integer) - The number of failed webhook deliveries.
- **successRate** (number) - The percentage of successful deliveries.

#### Response Example
{
  "totalDeliveries": 100,
  "successfulDeliveries": 95,
  "failedDeliveries": 5,
  "successRate": 0.95
}

### Error Handling
- **401 Unauthorized**: Returned if the API key is invalid or missing.
- **403 Forbidden**: Returned if the user does not have permission to access delivery statistics.
```

--------------------------------

### Successful Subscription Response (201)

Source: https://docs.lusha.com/apis/openapi/webhooks/createoptoutsubscription

A successful creation of an opt-out subscription will return a 201 status code with details of the created subscription.

```json
{
  "id": "6a0ca910b402df368d2aff07",
  "entityType": "contact",
  "entityId": "431705",
  "signalTypes": ["optOut"],
  "url": "https://example.com/webhook",
  "name": "Account opt-out webhook",
  "isActive": true,
  "createdAt": "2026-05-19T18:16:48.360Z",
  "updatedAt": "2026-05-19T18:16:48.360Z"
}
```

--------------------------------

### Webhooks

Source: https://docs.lusha.com/apis/openapi/section/available-endpoints

Real-time signal notifications via HTTP callbacks.

```APIDOC
## Webhooks

### Description
Real-time signal notifications via HTTP callbacks.

### Method
GET, POST (specific methods depend on implementation)

### Endpoint
/webhooks

### Parameters
(Specific parameters not detailed in the source text)

### Request Example
(Not provided in the source text)

### Response
(Specific response details not provided in the source text)
```

--------------------------------

### GET /v3/companies/signals/filters/{filterType}

Source: https://docs.lusha.com/apis/openapi/signals

Returns valid values for a single company signal filter type.

```APIDOC
## GET /v3/companies/signals/filters/{filterType}

### Description
Returns valid values for a single company signal filter type.

### Method
GET

### Endpoint
/v3/companies/signals/filters/{filterType}

### Parameters
#### Path Parameters
- **filterType** (string) - Required - The type of filter for which to retrieve values (e.g., `newsEventTypes`, `hiringByDepartments`, `hiringByLocations`).

### Response
#### Success Response (200)
- **values** (array of strings) - A list of valid values for the specified filter type.

#### Response Example
```json
{
  "values": [
    "funding",
    "acquisition",
    "ipo"
  ]
}
```
```

--------------------------------

### Get Contact Signal Types

Source: https://docs.lusha.com/apis/openapi/signals/getcontactsignaltypes

Returns the full list of supported signal types for contacts.

```APIDOC
## GET /v3/contacts/signals/types

### Description
Returns the full list of supported signal types for contacts.

### Method
GET

### Endpoint
/v3/contacts/signals/types

### Response
#### Success Response (200)
- `signalTypes` (array) - A list of supported signal types.

#### Response Example
{
  "signalTypes": ["allSignals","promotion","companyChange"]
}

#### Error Response (401)
- `statusCode` (integer, required) - HTTP status code
- `message` (string, required) - Error message
- `errors` (array) - Detailed error messages (optional)

#### Error Response (403)
- `statusCode` (integer, required) - HTTP status code
- `message` (string, required) - Error message
- `errors` (array) - Detailed error messages (optional)
```

--------------------------------

### Get Signal Options

Source: https://docs.lusha.com/apis/openapi/signals/getsignaloptions

Retrieve available signal options for filtering and querying. This is useful for understanding the types of real-world activities Lusha tracks.

```JavaScript
import { Lusha } from "lusha";

const lusha = new Lusha("YOUR_API_KEY");

lusha.signals.getSignalOptions().then(response => {
  console.log(response);
});
```

--------------------------------

### Get Company Filter Values

Source: https://docs.lusha.com/apis/openapi/filters

Returns valid values for a single company filter type.

```APIDOC
## GET /v3/companies/prospecting/filters/{filterType}

### Description
Returns valid values for a single company filter type.

### Method
GET

### Endpoint
/v3/companies/prospecting/filters/{filterType}

### Parameters
#### Path Parameters
- **filterType** (string) - Required - The type of company filter for which to retrieve values (e.g., `sizes`, `revenues`, `sics`, `names`, `technologies`, `locations`).

#### Query Parameters
- **searchQuery** (string) - Optional - A search query string. Required for filter types like `names`, `technologies`, `locations` (2-256 chars).

### Response
#### Success Response (200)
- **values** (array) - A list of valid values for the specified filter type.
```

--------------------------------

### POST /v3/companies/lookalike

Source: https://docs.lusha.com/apis/openapi.md

Find companies similar to a set of seed companies using AI-powered recommendations. Provide 5-100 seed companies via domains or LinkedIn URLs. The API returns lightweight company previews that can be enriched.

```APIDOC
## POST /v3/companies/lookalike

### Description
Finds companies similar to a provided set of seed companies using AI-powered recommendations. Accepts 5-100 seed companies and returns lightweight previews that can be further enriched.

### Method
POST

### Endpoint
/v3/companies/lookalike

### Parameters
#### Path Parameters
(No path parameters provided in the source text)

#### Query Parameters
- **dedupeSessionId** (string) - Optional - Used for pagination to get more results without repeating companies already seen. Generated on the first request if omitted.

#### Request Body
Provide 5-100 seed companies via domains or LinkedIn URLs.
Use the `exclude` field to always filter out specific companies.

### Request Example
(No request example provided in the source text)

### Response
#### Success Response (200)
(Details on success response are not provided in the source text)

#### Response Example
(No response example provided in the source text)
```

--------------------------------

### POST /v3/companies/search

Source: https://docs.lusha.com/apis/openapi

Look up companies by identifier. Returns a preview of each company profile. Accepts Lusha company id, name, or domain. Up to 100 companies per request.

```APIDOC
## POST /v3/companies/search

### Description
Look up companies by identifier. Returns a preview of each company profile.

### Method
POST

### Endpoint
/v3/companies/search

### Parameters
#### Query Parameters
- **signals** (string) - Optional - Filter to narrow results to companies showing specific activity.

#### Request Body
- **companies** (array) - Required - An array of company objects, each containing at least one of the following identifiers:
  - **id** (string) - Lusha company id
  - **name** (string)
  - **domain** (string)

### Request Example
```json
{
  "companies": [
    {
      "name": "Example Corp"
    }
  ]
}
```

### Response
#### Success Response (200)
- **has** (object) - Data points available via Enrich Companies.

#### Response Example
```json
{
  "companies": [
    {
      "id": "company_id_456",
      "has": {
        "firmographics": true,
        "locations": true
      }
    }
  ]
}
```
```

--------------------------------

### Get Contact Filter Values

Source: https://docs.lusha.com/apis/openapi/filters

Returns valid values for a single contact filter type.

```APIDOC
## GET /v3/contacts/prospecting/filters/{filterType}

### Description
Returns valid values for a single contact filter type.

### Method
GET

### Endpoint
/v3/contacts/prospecting/filters/{filterType}

### Parameters
#### Path Parameters
- **filterType** (string) - Required - The type of contact filter for which to retrieve values (e.g., `departments`, `seniority`, `countries`, `locations`).

#### Query Parameters
- **searchQuery** (string) - Optional - A search query string. Required for filter types like `locations` (2-256 chars).

### Response
#### Success Response (200)
- **values** (array) - A list of valid values for the specified filter type.
```

--------------------------------

### GET /api/subscriptions

Source: https://docs.lusha.com/apis/openapi/webhooks

Retrieves a list of all currently active webhook subscriptions for the account. Supports filtering and pagination.

```APIDOC
## GET /api/subscriptions

### Description
Retrieves a list of all currently active webhook subscriptions for the account. Supports filtering and pagination.

### Method
GET

### Endpoint
/api/subscriptions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of subscriptions to return per page. Defaults to 20.
- **offset** (integer) - Optional - The number of subscriptions to skip before returning results. Defaults to 0.
- **signalType** (string) - Optional - Filters subscriptions by signal type.
- **companyId** (string) - Optional - Filters subscriptions by company ID.
- **contactId** (string) - Optional - Filters subscriptions by contact ID.

### Response
#### Success Response (200)
- **subscriptions** (array) - An array of subscription objects.
  - **id** (string) - The unique identifier for the subscription.
  - **signalType** (string) - The type of signal subscribed to.
  - **url** (string) - The URL for webhook delivery.
  - **createdAt** (string) - The timestamp when the subscription was created.
- **total** (integer) - The total number of subscriptions matching the query.

#### Response Example
{
  "subscriptions": [
    {
      "id": "sub_abc123",
      "signalType": "job_change",
      "url": "https://your-webhook-url.com/event",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ],
  "total": 5
}

### Error Handling
- **401 Unauthorized**: Returned if the API key is invalid or missing.
- **403 Forbidden**: Returned if the user does not have permission to list subscriptions.
```

--------------------------------

### POST /api/subscriptions

Source: https://docs.lusha.com/apis/openapi/webhooks

Creates one or more webhook subscriptions for real-time signal notifications. Supports bulk creation up to 25 subscriptions per request. Webhook deliveries are retried automatically on failures and logged.

```APIDOC
## POST /api/subscriptions

### Description
Creates one or more webhook subscriptions for real-time signal notifications. Supports bulk creation up to 25 subscriptions per request. Webhook deliveries are retried automatically on failures and logged.

### Method
POST

### Endpoint
/api/subscriptions

### Parameters
#### Request Body
- **subscriptions** (array) - Required - An array of subscription objects to create.
  - **signalType** (string) - Required - The type of signal to subscribe to.
  - **contactId** (string) - Optional - The ID of the contact for contact-related signals.
  - **companyId** (string) - Optional - The ID of the company for company-related signals.
  - **url** (string) - Required - The URL to which webhook POST requests will be sent.

### Request Example
{
  "subscriptions": [
    {
      "signalType": "job_change",
      "contactId": "con_123",
      "url": "https://your-webhook-url.com/event"
    },
    {
      "signalType": "company_growth",
      "companyId": "com_456",
      "url": "https://your-webhook-url.com/event"
    }
  ]
}

### Response
#### Success Response (200)
- **subscriptions** (array) - An array of created subscription objects.
  - **id** (string) - The unique identifier for the subscription.
  - **signalType** (string) - The type of signal subscribed to.
  - **url** (string) - The URL for webhook delivery.
  - **createdAt** (string) - The timestamp when the subscription was created.

#### Response Example
{
  "subscriptions": [
    {
      "id": "sub_abc123",
      "signalType": "job_change",
      "url": "https://your-webhook-url.com/event",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ]
}

### Error Handling
- **400 Bad Request**: Returned if the request body is invalid or missing required fields.
- **401 Unauthorized**: Returned if the API key is invalid or missing.
- **403 Forbidden**: Returned if the user does not have permission to create subscriptions.
- **429 Too Many Requests**: Returned if the rate limit is exceeded.
```

--------------------------------

### Create Opt-Out Subscription

Source: https://docs.lusha.com/apis/openapi/webhooks/createoptoutsubscription

Creates a subscription to receive webhook notifications when a contact opts out. Lusha will deliver a POST request to your specified URL with the opt-out details.

```APIDOC
## POST /api/subscriptions/opt-out

### Description
Subscribes to real-time notifications when a contact opts out of data processing. Lusha will send an OptOutWebhookPayload to your endpoint.

### Method
POST

### Endpoint
/api/subscriptions/opt-out

### Security
ApiKeyAuth

### Parameters
#### Request Body
- **entityType** (string, required) - Entity type for opt-out subscriptions. Currently only 'contact' is supported.
- **url** (string, required) - Your webhook endpoint URL (HTTPS required in production). Example: "https://example.com/webhook"
- **name** (string, optional) - Descriptive name for this subscription. Example: "Account opt-out webhook"

### Response
#### Success Response (201)
- **id** (string, required) - Example: "6a0ca910b402df368d2aff07"
- **entityType** (string, required) - Enum: "contact"
- **entityId** (string, required) - Example: "431705"
- **signalTypes** (array, required) - Example: ["optOut"]
- **url** (string, required) - Example: "https://example.com/webhook"
- **name** (string, optional) - Example: "Account opt-out webhook"
- **isActive** (boolean, required) - Example: true
- **createdAt** (string, required) - Example: "2026-05-19T18:16:48.360Z"
- **updatedAt** (string, required) - Example: "2026-05-19T18:16:48.360Z"

#### Error Response (400)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array, optional) - Detailed error messages. Example: ["entityType must be one of: contact, company"]

#### Error Response (401)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array, optional) - Detailed error messages. Example: ["entityType must be one of: contact, company"]

#### Error Response (403)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array, optional) - Detailed error messages. Example: ["entityType must be one of: contact, company"]

#### Error Response (500)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array, optional) - Detailed error messages. Example: ["entityType must be one of: contact, company"]
```

--------------------------------

### Get Companies Signals

Source: https://docs.lusha.com/apis/openapi/signals/getsignaloptions

Retrieve real-world activity data for companies. This endpoint can be used independently or with filters.

```APIDOC
## Get Companies Signals

### Description
Retrieves real-world activity data for companies. This endpoint can be used to fetch specific signals or to apply signal filters to company searches.

### Method
POST

### Endpoint
/v3/companies/signals

### Request Body
- **filter** (object) - Optional - Filters to apply to the signal search. See `signals/types` and `signals/filters` for available options.
  - **signals** (array) - Optional - List of company signal types to retrieve. Example: `["headcountIncrease1m", "websiteTrafficDecrease"]`
  - **showSignalsCompany** (boolean) - Optional - If true, includes signal data in the response. Charged per matched signal.
- **searchRequest** (object) - Optional - Parameters for searching companies. Can include identifiers or filters.
  - **id** (string) - Optional - Company ID.
  - **name** (string) - Optional - Company name.
  - **domain** (string) - Optional - Company domain.

### Request Example
```json
{
  "filter": {
    "signals": ["headcountIncrease1m"],
    "showSignalsCompany": true
  },
  "searchRequest": {
    "domain": "example.com"
  }
}
```

### Response
#### Success Response (200)
- **companies** (array) - A list of company objects, each containing firmographic data and associated signals.
  - **signals** (object) - Contains details about the signals found for the company.
```

--------------------------------

### POST /v3/companies/lookalike

Source: https://docs.lusha.com/apis/openapi/lookalikes/getcompanylookalikes

Finds companies similar to a provided set of seed companies. It supports pagination and exclusion of specific companies. Results are lightweight previews and can be enriched using the 'Enrich Companies' endpoint.

```APIDOC
## POST /v3/companies/lookalike

### Description
Finds companies similar to a provided set of seed companies. It supports pagination and exclusion of specific companies. Results are lightweight previews and can be enriched using the 'Enrich Companies' endpoint.

### Method
POST

### Endpoint
/v3/companies/lookalike

### Parameters
#### Request Body
- **dedupeSessionId** (string) - Optional - Used for pagination to retrieve subsequent results without duplicates. If omitted in the first request, the server generates and returns one.
- **seeds** (object) - Required - An object containing the seed companies to find lookalikes for.
  - **seeds.domains** (array) - Example: ["sap.com","oracle.com"]
  - **seeds.linkedinUrls** (array) - Example: ["https://www.linkedin.com/company/sap"]
- **exclude** (object) - Optional - An object used to filter out specific companies.
- **limit** (integer) - Optional - The maximum number of results to return. Example: 25

### Request Example
```json
{
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "seeds": {
    "domains": ["sap.com", "oracle.com"]
  },
  "exclude": {},
  "limit": 25
}
```

### Response
#### Success Response (200)
- **dedupeSessionId** (string, required) - The session ID for pagination.
- **results** (array, required) - A list of lightweight company previews.
  - **results.id** (string) - The unique identifier for the company. Example: "16303253"
  - **results.name** (string) - The name of the company. Example: "Marriott International"
  - **results.domain** (string) - The primary domain of the company. Example: "marriott.com"
  - **results.employeeCount** (object) - Information about the company's employee count.
    - **results.employeeCount.exact** (integer) - The exact number of employees. Example: 255334
  - **results.industry** (string) - The industry the company operates in. Example: "Hospitality"
  - **results.location** (object) - The company's location.
    - **results.location.country** (string) - The country of the company's location. Example: "United States"
    - **results.location.state** (string) - The state of the company's location. Example: "Maryland"
    - **results.location.city** (string) - The city of the company's location. Example: "Bethesda"
  - **results.socialLinks** (object) - Social media links for the company.
    - **results.socialLinks.linkedin** (string) - The LinkedIn profile URL. Example: "https://www.linkedin.com/company/marriott-international"
- **meta** (object, required) - Metadata about the results.
  - **meta.returned** (integer, required) - The number of results returned in this request. Example: 1
  - **meta.hasMore** (boolean, required) - Indicates if there are more results available. Example: true
- **billing** (object) - Credit usage summary for the request.
  - **billing.creditsCharged** (integer) - Total credits charged for this request. Example: 3
  - **billing.resultsReturned** (integer) - Number of successful results returned. Example: 1

#### Error Response (400)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array) - Detailed error messages (optional, only for validation errors). Example: ["entityType must be one of: contact, company"]

#### Error Response (403)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array) - Detailed error messages (optional, only for validation errors). Example: ["entityType must be one of: contact, company"]

#### Error Response (410)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array) - Detailed error messages (optional, only for validation errors). Example: ["entityType must be one of: contact, company"]

#### Error Response (500)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array) - Detailed error messages (optional, only for validation errors). Example: ["entityType must be one of: contact, company"]

#### Error Response (402)
- **statusCode** (integer, required) - HTTP status code. Example: 400
- **message** (string, required) - Error message. Example: "Validation failed"
- **errors** (array) - Detailed error messages (optional, only for validation errors). Example: ["entityType must be one of: contact, company"]

```

--------------------------------

### Get Contacts Signals

Source: https://docs.lusha.com/apis/openapi/signals/getsignaloptions

Retrieve real-world activity data for contacts. This endpoint can be used independently or with filters.

```APIDOC
## Get Contacts Signals

### Description
Retrieves real-world activity data for contacts. This endpoint can be used to fetch specific signals or to apply signal filters to contact searches.

### Method
POST

### Endpoint
/v3/contacts/signals

### Request Body
- **filter** (object) - Optional - Filters to apply to the signal search. See `signals/types` and `signals/filters` for available options.
  - **signals** (array) - Optional - List of contact signal types to retrieve. Example: `["promotion", "companyChange"]`
  - **showSignalsContact** (boolean) - Optional - If true, includes signal data in the response. Charged per matched signal.
- **searchRequest** (object) - Optional - Parameters for searching contacts. Can include identifiers or filters.
  - **id** (string) - Optional - Contact ID.
  - **email** (string) - Optional - Contact email.
  - **linkedinUrl** (string) - Optional - Contact LinkedIn URL.
  - **firstName** (string) - Optional - Contact first name.
  - **lastName** (string) - Optional - Contact last name.
  - **companyName** (string) - Optional - Company name.
  - **companyDomain** (string) - Optional - Company domain.

### Request Example
```json
{
  "filter": {
    "signals": ["promotion"],
    "showSignalsContact": true
  },
  "searchRequest": {
    "email": "john.doe@example.com"
  }
}
```

### Response
#### Success Response (200)
- **contacts** (array) - A list of contact objects, each containing profile data and associated signals.
  - **signals** (object) - Contains details about the signals found for the contact.
```