Create Subscription

POST

api

subscriptions

curl --request POST \
  --url https://api.lusha.com/api/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "defaults": {
    "entityType": "contact",
    "signalTypes": [
      "promotion",
      "companyChange"
    ],
    "url": "https://example.com/webhooks/lusha"
  },
  "subscriptions": [
    {
      "entityId": "123456",
      "name": "My Test Webhook"
    }
  ]
}
'

{
  "total": 1,
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439011",
        "entityType": "contact",
        "entityId": "123456",
        "signalTypes": ["promotion", "companyChange"],
        "url": "https://example.com/webhooks/lusha",
        "name": "My Test Webhook",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    }
  ]
}

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

Send a single request to subscribe one or more contacts or companies to real-time signal notifications. Each subscription links an entity to a webhook URL and the set of signal types you want to receive. Lusha delivers a signed JSON payload to your endpoint whenever a matching signal fires.

Your account must have a webhook secret before deliveries can be received. Generate one by calling POST /api/account/secret/regenerate and store it securely - it is shown only once.

Endpoint: POST https://api.lusha.com/api/subscriptions

You can create up to 25 subscriptions per request.

Request body

object

required

Default values applied to every subscription in the request, unless overridden per item.

Show properties

string

required

The HTTPS URL where Lusha will POST signal payloads. HTTP URLs are not accepted in production. Maximum length 2048 characters.

string

Default entity type for all subscriptions in the request. Accepted values: contact, company. Can be overridden per subscription item.

string[]

Default signal type keys for all subscriptions in the request. Available signals depend on entity type - see Contact Signal Types or Company Signal Types for the full list. Can be overridden per subscription item.

string

Default subscription name prefix, applied unless a subscription item specifies its own name. Maximum 100 characters.

object[]

required

Array of subscriptions to create. Minimum 1, maximum 25 items per request (10 in development environments).

Show properties

string

required

The unique identifier of the contact or company to subscribe to. Maximum length 255 characters.

string

Overrides defaults.entityType for this item. Accepted values: contact, company.

string[]

Overrides defaults.signalTypes for this item.

string

Overrides the default name for this item. Maximum 100 characters.

Example request

cURL

curl --request POST \
  --url https://api.lusha.com/api/subscriptions \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "defaults": {
      "url": "https://example.com/webhooks/lusha",
      "entityType": "contact",
      "signalTypes": ["promotion", "companyChange"]
    },
    "subscriptions": [
      { "entityId": "123456", "name": "My Test Webhook" }
    ]
  }'

Example response

{
  "total": 1,
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439011",
        "entityType": "contact",
        "entityId": "123456",
        "signalTypes": ["promotion", "companyChange"],
        "url": "https://example.com/webhooks/lusha",
        "name": "My Test Webhook",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    }
  ]
}

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

integer

Total number of subscription creation attempts.

integer

Number of subscriptions created successfully.

integer

Number of subscription creation attempts that failed.

object[]

One entry per item in the request subscriptions array, in the same order. Each entry has index and success, plus either a subscription object (on success) or an error object with code and message (on failure) - for example a DUPLICATE_SUBSCRIPTION error if the entity is already subscribed.

This endpoint supports partial success: some subscriptions in the request can be created while others fail (for example, due to a duplicate entity). Check failed and inspect results to see which items succeeded.

Webhook payload structure

When a signal fires, Lusha sends a POST request to the subscription’s webhook URL. The payload structure depends on the signal type.

{
  "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
  }
}

{
  "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
  }
}

Delivery headers

Lusha includes the following headers in every webhook delivery:

Header	Description
`X-Lusha-Signature`	HMAC-SHA256 signature for verifying the request came from Lusha
`X-Lusha-Timestamp`	Unix timestamp of when the request was sent
`Content-Type`	`application/json`
`User-Agent`	`Lusha-Webhooks/1.0`

Required acknowledgment response

Your endpoint must respond within 10 seconds with an HTTP 2xx status and the following JSON body:

{
  "received": true,
  "timestamp": "2026-02-05T10:30:45.123Z",
  "webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c"
}

boolean

required

Must be true to confirm receipt.

string

required

ISO 8601 timestamp of when your server received the request.

string

required

The id value copied from the incoming webhook payload.

Return the acknowledgment before performing any heavy processing. Queue the payload for async handling if needed:

app.post('/webhook', async (req, res) => {
  // 1. Verify signature first
  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
  });
});

Delivery and retry behavior

Lusha retries failed deliveries up to 3 times with exponential backoff.
A non-2xx response or a timeout triggers the retry mechanism.
After all 3 retries are exhausted, the subscription is automatically disabled.
All delivery attempts are recorded in audit logs.

Retries do not incur additional credit charges. Each signal is charged once, at the time it is first delivered.

Error responses

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

Field	Type	Description
`statusCode`	number	HTTP status code
`message`	string	Human-readable error message
`errors`	string[]	Detailed validation errors (optional)

Authorizations

api_key

string

header

required

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.

Body

application/json

defaults

object

required

Show child attributes

subscriptions

object[]

required

Array of subscriptions to create (max 25)

Required array length: 1 - 25 elements

Show child attributes

name

string

Default subscription name prefix

Maximum string length: 100

Example:

"Contact Webhook"

Response

Subscriptions created (full or partial success)

total

integer

required

Example:

3

successful

integer

required

Example:

2

failed

integer

required

Example:

1

results

object[]

required

Option 1
Option 2

Show child attributes

⌘I

curl --request POST \
  --url https://api.lusha.com/api/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "defaults": {
    "entityType": "contact",
    "signalTypes": [
      "promotion",
      "companyChange"
    ],
    "url": "https://example.com/webhooks/lusha"
  },
  "subscriptions": [
    {
      "entityId": "123456",
      "name": "My Test Webhook"
    }
  ]
}
'

{
  "total": 1,
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439011",
        "entityType": "contact",
        "entityId": "123456",
        "signalTypes": ["promotion", "companyChange"],
        "url": "https://example.com/webhooks/lusha",
        "name": "My Test Webhook",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    }
  ]
}

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

Overview

Resources

Endpoints

Request body

Example request

Example response

Webhook payload structure

Delivery headers

Required acknowledgment response

Delivery and retry behavior

Error responses

Authorizations

Body

Response

​Request body

​Example request

​Example response

​Webhook payload structure

​Delivery headers

​Required acknowledgment response

​Delivery and retry behavior

​Error responses

Authorizations

Body

Response

Request body

Example request

Example response

Webhook payload structure

Delivery headers

Required acknowledgment response

Delivery and retry behavior

Error responses