Lusha API Documentation

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Creates one or more webhook subscriptions for real-time signal notifications.

URL Validation:

• The URL is validated once before creating any subscriptions
• Includes format checking and challenge request verification
• If URL validation fails, no subscriptions are created

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

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:

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

Headers Included:

⚠️ Important: Ensure your account has a webhook secret before creating subscriptions. Create one via the Regenerate Account Secret endpoint.

Returns all webhook subscriptions for your account with pagination support.

Endpoint: (GET) https://api.lusha.com/api/subscriptions

Pagination:

• Results are sorted by createdAt in descending order (newest first)
• Default limit: 10, max limit: 100
• Use offset for pagination through large result sets

Note: The webhook secret is never returned in list responses for security.

Returns a single webhook subscription by ID.

Endpoint: (GET) https://api.lusha.com/api/subscriptions/{id}

Updates an existing webhook subscription. All fields are optional.

Endpoint: (PATCH) https://api.lusha.com/api/subscriptions/{id}

Reactivating Disabled Subscriptions:

When setting isActive: true on a previously disabled subscription, the system automatically:

• Clears the blockReason field
• Clears the blockedAt timestamp
• Resets the retry counter

Regenerating Secrets:

Set regenerateSecret: true to generate a new webhook secret. The new secret:

• Affects all subscriptions for your account
• Is only shown once in the response
• Immediately invalidates the old secret

Test a webhook subscription by sending a test signal. Supports three test modes.

Endpoint: (POST) https://api.lusha.com/api/subscriptions/{id}/test

Test Modes:

• direct - Quick HTTP check only (validates URL responds correctly)
• kafka - Fanout handler only (tests Kafka message processing)
• full - Complete Kafka flow (default - end-to-end test)

What Gets Tested:

• URL accessibility and response time
• Challenge verification (for direct mode)
• Complete delivery pipeline (for full mode)
• Signature generation and headers

Important Notes:

• Test deliveries do NOT consume credits
• Test payloads use mock data
• Useful for verifying webhook configuration before going live

Delete one or more webhook subscriptions. Returns detailed results for each deletion with partial success support.

Endpoint: (POST) https://api.lusha.com/api/subscriptions/delete

Behavior:

• Each subscription is processed independently
• Returns detailed results for each item including deleted subscription info
• Invalid ID formats are gracefully handled and reported as NOT_FOUND
• Duplicate IDs are automatically deduplicated
• Deletion is permanent and cannot be undone

Retrieve webhook delivery logs for your account.

Endpoint: (GET) https://api.lusha.com/api/audit-logs

What's Logged:

• All webhook delivery attempts (success and failures)
• HTTP status codes and response times
• Error messages for failed deliveries
• Delivery timestamps and duration metrics

Filtering:

• Filter by subscription ID to see logs for specific subscriptions
• Filter by status to see only successes, failures, or permanent failures

Rate Limit: 100 requests/minute per account

Note: Logs are retained for 90 days (successful) and 180 days (failed/DLQ)