# 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:
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 for details.

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

Endpoint: POST /api/subscriptions/opt-out
Security: ApiKeyAuth

## Request fields (application/json):

  - `entityType` (string, required)
    Entity type for opt-out subscriptions. Currently only contact is supported.
    Enum: "contact"

  - `url` (string, required)
    Your webhook endpoint URL (HTTPS required in production)
    Example: "https://example.com/webhook"

  - `name` (string)
    Descriptive name for this subscription
    Example: "Account opt-out webhook"

## Response 201 fields (application/json):

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

## Response 400 fields (application/json):

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

## Response 401 fields (application/json):

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

## Response 403 fields (application/json):

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

## Response 500 fields (application/json):

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