> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apten.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Unsubscribe a lead

> Unsubscribes a lead from one or more channels (SMS, voice, email). Does not change whether Apten is on for the lead or add the lead's phone number to the Do Not Contact (DNC) list.

### Notes

Unsubscribes a lead from one or more channels. Pass a `channels` array (`sms`, `voice`, `email`) in the request body to target specific channels. When `channels` is omitted, Apten unsubscribes every channel the lead can actually receive: SMS and voice if the lead has a phone number, email if the lead has an email address.

The `200` response `channels` array is the set that was applied, not the set that was requested. A lead with a phone number and no email who sends `{}` is unsubscribed from SMS and voice, and the response is `["sms", "voice"]`.

SMS and voice opt-outs may be coupled according to your organization's settings. When those channels are coupled, requesting either one unsubscribes both.

If every requested channel is missing on the lead, the request fails with a `400`. An explicit `{"channels":["email"]}` on a lead with no email returns `Lead has no email`. An explicit request that includes at least one reachable channel still succeeds for those channels.

Repeated requests converge on the same subscription state. Channels that are already unsubscribed remain unchanged, and no duplicate opt-out webhook is emitted for those channels.

**Choose the right control:**

* **Pause the AI:** Use [Turn off a lead](/api-reference/leads/turn-off). This pauses Apten for the lead but does not change their subscription status.
* **Opt out of contact:** Use this endpoint. It changes the lead's subscription status for the selected channels.
* **Never contact this number:** Use the [Do Not Contact API](/api-reference/dnc/register). This adds the phone number to your organization's DNC list.

**Side effects:**

* Emits an [opt-out webhook event](/webhooks/opt-out) for each channel that transitions to unsubscribed.
* Does not change whether Apten is on for the lead.
* Does not add the lead's phone number to the DNC list.

To undo an SMS opt-out, the lead can text `START`, or you can use [Resubscribe a lead](/api-reference/leads/resubscribe) for the applicable channels. Carrier-level SMS blocks can only be cleared by texting `START`.


## OpenAPI

````yaml post /leads/{leadId}/unsubscribe
openapi: 3.0.1
info:
  title: AttentPublicAPI
  version: '2024-05-17T21:09:13Z'
servers:
  - url: https://api.attent.app/v1
security: []
paths:
  /leads/{leadId}/unsubscribe:
    post:
      description: >-
        Unsubscribes a lead from one or more channels (SMS, voice, email). Does
        not change whether Apten is on for the lead or add the lead's phone
        number to the Do Not Contact (DNC) list.
      parameters:
        - name: leadId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the lead to unsubscribe.
      requestBody:
        description: >-
          Channels to unsubscribe. Optional; when omitted, defaults to every
          channel the lead can receive.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                channels:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - sms
                      - voice
                      - email
                  description: >-
                    The channels to unsubscribe the lead from. When omitted,
                    Apten unsubscribes every channel the lead can receive (phone
                    → sms and voice, email → email).
            example:
              channels:
                - sms
      responses:
        '200':
          description: Lead unsubscribed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Returns "Lead unsubscribed successfully." if the lead was
                      unsubscribed.
                  channels:
                    type: array
                    items:
                      type: string
                      enum:
                        - sms
                        - voice
                        - email
                    description: >-
                      The channels that were applied. Channels the lead cannot
                      receive (no phone or no email) are omitted.
              example:
                message: Lead unsubscribed successfully.
                channels:
                  - sms
        '400':
          description: >-
            Bad request. Returned when no valid channels are provided, the
            request body is invalid, or none of the requested channels are
            available on the lead (for example, an explicit email unsubscribe
            when the lead has no email).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                invalidChannels:
                  value:
                    message: 'channels must include at least one of: sms, voice, email'
                noEmail:
                  value:
                    message: Lead has no email
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Lead not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: 'Resource not found: Lead with id 12345'
        '500':
          $ref: '#/components/responses/500'
      security:
        - api_key: []
components:
  responses:
    '403':
      description: Forbidden API key
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            example:
              message: Forbidden
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            example:
              message: Internal Server Error
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````