v1

latestOpenAPI 3.0.3Proprietary2026-08-0656136286.9 KB

Webhooks

Create Opt-Out Subscription

Subscribe to real-time notifications when a contact opts out of data processing. When a contact requests removal, Lusha sends an OptOutWebhookPayload to your endpoint so you can action the removal in your own systems (CRM, outreach tools, etc.).

Endpoint: (POST) https://api.lusha.com/api/subscriptions/opt-out

How it works:

Create one opt-out subscription per account (scoped to contact entity type)
Lusha delivers a POST request to your URL whenever a contact opts out
The payload includes the contact identity, opt-out date, and the specific data points (emails and/or phones) that must be removed

Payload you'll receive:

{
  "contactId": "987654321",
  "fullName": "Jane Doe",
  "companyName": "Acme Corp",
  "jobTitle": "Director of Product",
  "linkedinUrl": "https://www.linkedin.com/in/jane-doe",
  "contactOptOutDate": "2026-04-22 14:32:11.412",
  "contactExposureDate": "2025-08-03 09:15:47",
  "datapoints": [
    { "datapointId": "+14155550199", "datapointType": "phone" },
    { "datapointId": "jane.doe@acme.com", "datapointType": "email" }
  ],
  "partnerClientId": "acme-crm-tenant-42"
}

Important: Signature verification applies the same way as standard webhook deliveries. See Security & Verification for details.

Note: Ensure your account has a webhook secret before creating this subscription. See Regenerate Account Secret.

post/api/subscriptions/opt-out

Request body

entityType'contact' required

Entity type for opt-out subscriptions. Currently only contact is supported.

urlstring uri required

Your webhook endpoint URL (HTTPS required in production)

namestring

Descriptive name for this subscription

Example request

{
  "entityType": "contact",
  "url": "https://example.com/webhook",
  "name": "Account opt-out webhook"
}

Response

Opt-out subscription created successfully

idstring required

entityType'contact' required

entityIdstring required

signalTypesstring[] required

urlstring uri required

namestring

isActiveboolean required

createdAtstring date-time required

updatedAtstring date-time required

Example response

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