---
title: "Create Opt-Out Subscription"
method: POST
path: "/api/subscriptions/opt-out"
tags: ["Webhooks"]
---

# Create Opt-Out Subscription

`POST /api/subscriptions/opt-out`

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:**
```json
{
  "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](#tag/Webhooks) for details.

> **Note:** Ensure your account has a webhook secret before creating this subscription. See [Regenerate Account Secret](#operation/regenerateAccountSecret).

## Request body

- CreateOptOutSubscriptionRequest — Request body for creating an opt-out webhook subscription
  - `entityType` 'contact', required — Entity type for opt-out subscriptions. Currently only `contact` is supported.
  - `url` string, uri, required — Your webhook endpoint URL (HTTPS required in production)
  - `name` string — Descriptive name for this subscription

## Response `201`

Opt-out subscription created successfully

- OptOutSubscriptionResponse — Response body returned when an opt-out subscription is created successfully
  - `id` string, required
  - `entityType` 'contact', required
  - `entityId` string, required
  - `signalTypes` string[], required
  - `url` string, uri, required
  - `name` string
  - `isActive` boolean, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400` — Bad request - invalid input data
- `401` — Unauthorized - invalid or missing API key
- `403` — Forbidden - feature not available or opt-out subscription already exists
- `500` — Internal server error

---

[API](https://skmtc.net/lusha/apis/lusha-api-documentation.md) · [All operations](https://skmtc.net/lusha/apis/lusha-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lusha/lusha-api-documentation/revisions/4c51e40e3e67/schema)