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

# Quick Start

> Add, query, and remove an identity from the do-not-contact list in a few minutes.

<Tip>
  From **list entry to first block** in a few steps. The API Key needs scopes `suppressions:read` and `suppressions:write`.
</Tip>

## In brief

* **Add** email, phone, Telegram, or Instagram to the global do-not-contact list.
* **Query** entries with filters by type, reason, and search.
* **Remove** by ID or by identity when the customer agrees to receive messages again.

Context: [Introduction](/en/suppressions-api/como-funciona/introducao). Scopes: [API Key scopes](/en/suppressions-api/como-funciona/escopos-da-api-key).

## Before you start

| Item                              | Required                                           |
| --------------------------------- | -------------------------------------------------- |
| Key with **`suppressions:write`** | Yes, to add or remove                              |
| Key with **`suppressions:read`**  | Yes, to list and query                             |
| Auth                              | `Authorization: Bearer sk_live_...` or `x-api-key` |

Base URL: `https://api.notifique.dev`.

***

## 1. Add to the list

A phone number blocks **SMS, WhatsApp, RCS, and voice** at once — like putting the number in the front-desk notebook.

```http theme={null}
POST /v1/suppressions
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "type": "phone",
  "value": "+55 (11) 99999-0000",
  "reason": "manual",
  "note": "Customer asked not to be contacted"
}
```

Expected response: **201** (new entry) or **200** (already existed, idempotent). The API normalizes the phone to E.164 before saving.

<Note>
  The addition is **idempotent**: if the identity is already active, the API returns the existing entry without duplicating.
</Note>

### Email, Telegram, or Instagram

```json theme={null}
{
  "type": "email",
  "value": "User@Example.com",
  "reason": "complaint",
  "note": "Marked as spam"
}
```

Formatting details: [Normalization by type](/en/suppressions-api/como-funciona/normalizacao).

***

## 2. List and query

**List** with optional filters:

```http theme={null}
GET /v1/suppressions?type=phone&limit=20&page=1
Authorization: Bearer sk_live_xxxxx
```

Useful parameters: `type`, `reason`, `origin`, `channel`, `search`.

**Query a single entry** by ID returned from POST:

```http theme={null}
GET /v1/suppressions/{id}
Authorization: Bearer sk_live_xxxxx
```

***

## 3. Remove from the list

By ID:

```http theme={null}
DELETE /v1/suppressions/{id}
Authorization: Bearer sk_live_xxxxx
```

By identity (no ID needed):

```http theme={null}
DELETE /v1/suppressions/by-identity
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "type": "email",
  "value": "cliente@example.com"
}
```

<Warning>
  Removal **re-enables sending immediately**. If the address generates bounce, complaint, or `STOP` again, it may be suppressed again automatically.
</Warning>

***

## 4. Batch import

In the API, send up to **100** items per call:

```http theme={null}
POST /v1/suppressions/batch/add
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "entries": [
    { "type": "phone", "value": "5511999990000", "reason": "manual" },
    { "type": "email", "value": "bounce@example.com", "reason": "bounce" }
  ]
}
```

Each item returns an individual status: added, already exists, or invalid.

In the **dashboard** (**Audience → Suppressions**), import CSV/XLSX with headers `type,value,reason` — up to 1,000 rows, in batches of 100. The `channel` column in the CSV is import context in the dashboard; on API v1 blocking follows `type` (phone blocks sms/whatsapp/rcs/voice).

To remove in batch: `POST /v1/suppressions/batch/remove` with `ids` and/or `identities`.

***

## Next steps

* [Normalization](/en/suppressions-api/como-funciona/normalizacao): how the API handles each type
* [Webhook events](/en/suppressions-api/como-funciona/eventos-do-webhooks): know when someone enters or leaves the list
* [Troubleshooting](/en/suppressions-api/como-funciona/troubleshooting): common codes