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

# Opt-Outs Overview

> Sync your own consent records with Connectly — suppress contacts so campaigns and messages skip them, and re-enable the ones who opt back in 🚫

The Opt-Outs API keeps Connectly's suppression list in step with the consent records in your own system. Send the contacts you must not message and Connectly stops delivering to them; send the ones who opted back in and Connectly resumes.

Both routes are symmetric and safe to repeat, so the same daily export can be sent every night without special handling for what changed since yesterday.

## How it works

<Steps>
  <Step title="Export your consent changes">
    Produce the list of contacts to suppress and the list to re-enable. Repeats inside one list are fine — the same contact listed twice counts once.
  </Step>

  <Step title="Suppress">
    Call [Add opt-outs](https://docs.connectly.ai/opt-outs/add-opt-outs) with up to 10,000 contacts. Campaigns and messages skip them from that point on.
  </Step>

  <Step title="Re-enable">
    Call [Remove opt-outs](https://docs.connectly.ai/opt-outs/remove-opt-outs) for contacts who consented again. This reverses only the suppressions this API recorded.
  </Step>

  <Step title="Reconcile">
    Each response reports what changed, what was already in that state, and which entries could not be read. Unreadable entries are dropped and counted rather than failing the whole batch.
  </Step>
</Steps>

<Warning>
  **Remove only reverses what this API suppressed.** A contact who replied STOP, tapped an unsubscribe button, turned marketing off in WhatsApp itself, or was uploaded through the Audience screen in Connectly stays suppressed. Those contacts come back under `notOptedOutCount`, and messages to them are still blocked.

  This is deliberate. Your re-enable list is your record of who consented with you — it is not evidence that someone who opted out on the channel itself changed their mind.
</Warning>

## Identifying a contact

Every entry names one contact through either field:

| Field    | Accepts                                                                                                                                        |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | An E.164 phone number (`+14155558234`), with or without the leading `+`.                                                                       |
| `userId` | A [Business-Scoped User ID](https://docs.connectly.ai/messaging/bsuid) (`US.13491208655302741918`), exactly as Connectly sends it in webhooks. |

`client` takes precedence when both are set. `userId` is read only when `client` is empty.

These are the same identifier rules as [Send Campaigns](https://docs.connectly.ai/campaigns/send-campaigns), so a system that already targets contacts for campaigns can suppress them without a second identifier mapping.

<Note>
  Opt-outs are recorded per channel. Both routes act on WhatsApp.
</Note>

## Endpoints

<CardGroup cols={2}>
  <Card title="Add opt-outs" icon="ban" href="https://docs.connectly.ai/opt-outs/add-opt-outs">
    `POST /v1/businesses/{businessId}/add/opt_outs` — suppress up to 10,000 contacts.
  </Card>

  <Card title="Remove opt-outs" icon="arrow-rotate-left" href="https://docs.connectly.ai/opt-outs/remove-opt-outs">
    `POST /v1/businesses/{businessId}/remove/opt_outs` — re-enable contacts this API suppressed.
  </Card>
</CardGroup>