# Blocked contacts

> Silence the agent for a number or a whole dial prefix, list and remove your rules, and understand what a block does and does not do.

Source: https://docs.whatsetter.com/developers/guides/blocked-contacts/

A blocked contact is a number, or a dial prefix, the agent must ignore: spam, competitors, countries you do not serve. The API manages the same rules as **Blocked numbers** in the dashboard's **Settings**.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/blocked-contacts`](/api-reference/operations/listblockedcontacts/) | `blocklist:manage` |
| POST | [`/blocked-contacts`](/api-reference/operations/createblockedcontact/) | `blocklist:manage` |
| DELETE | [`/blocked-contacts/{id}`](/api-reference/operations/deleteblockedcontact/) | `blocklist:manage` |

## What a block does

- The agent **no longer replies** to the contact and **no longer follows up**.
- Incoming messages are **still stored** and visible in the conversation, so your team sees what happens and can still answer by hand.
- It is not a WhatsApp-level block: the person can still write to the number.

A rule applies to the whole workspace, every agent: `campaign_id` is `null`, whether the rule was created here or in the dashboard.

## List rules

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/blocked-contacts?kind=prefix&limit=50" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/blocked-contacts?kind=prefix&limit=50', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: rules, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/blocked-contacts",
    params={"kind": "prefix", "limit": 50},
    headers={"Authorization": "Bearer ws_live_…"},
)
rules = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c141",
      "kind": "number",
      "value": "33612345678",
      "phone": "+33612345678",
      "label": "Spammer",
      "reason": null,
      "campaign_id": null,
      "created_at": "2026-09-15T12:00:00.000Z"
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c142",
      "kind": "prefix",
      "value": "91",
      "phone": null,
      "label": "India",
      "reason": "Out of market",
      "campaign_id": null,
      "created_at": "2026-09-15T12:01:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

`kind` filters on `number` or `prefix`; `limit` is 1 to 100, 50 by default. `phone` is the number with a `+` for a `number` rule on a real phone, `null` for a prefix or a masked WhatsApp id.

## Block a number

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/blocked-contacts" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"number","phone":"+33 6 12 34 56 78","label":"Spammer","reason":"Sends ads every day"}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/blocked-contacts', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ kind: 'number', phone: '+33 6 12 34 56 78', label: 'Spammer', reason: 'Sends ads every day' }),
});
const { data: rule } = await res.json(); // 201
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/blocked-contacts",
    headers={"Authorization": "Bearer ws_live_…"},
    json={"kind": "number", "phone": "+33 6 12 34 56 78", "label": "Spammer", "reason": "Sends ads every day"},
)
rule = r.json()["data"]  # 201
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c141",
    "kind": "number",
    "value": "33612345678",
    "phone": "+33612345678",
    "label": "Spammer",
    "reason": "Sends ads every day",
    "campaign_id": null,
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}
```

`phone` accepts any international format; spaces and punctuation are ignored. `label` (up to 80 characters) and `reason` (up to 500) are optional.

## Block a dial prefix

```json
{ "kind": "prefix", "prefix": "+91", "label": "India", "reason": "Out of market" }
```

`prefix` is 1 to 4 digits, with or without the `+`. Send it to the same `POST /blocked-contacts`; the response has the same shape, with `kind: "prefix"` and `phone: null`.

## Remove a rule

**cURL**

```bash
curl -X DELETE "https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
await fetch('https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer ws_live_…' },
}); // 204
```

**Python**

```python
import requests

requests.delete(
    "https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141",
    headers={"Authorization": "Bearer ws_live_…"},
)  # 204
```

`204` with no body. The agent answers the contact again from the next message.

## The match rule

- A `number` rule matches the exact WhatsApp id: `33612345678` blocks `+33612345678` and nothing else.
- A `prefix` rule matches every number that starts with those digits: `91` blocks all of India. It only applies to real phone numbers: a masked WhatsApp id or an Instagram thread carries no country and is never matched by a prefix.
- Group threads are never blocked by these rules.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `blocklist:manage`. |
| 404 | `not_found` | Unknown rule, or a rule of another workspace. |
| 409 | `already_blocked` | The same number or prefix is already blocked. |
| 422 | `validation_error` | Unknown `kind`, unusable `phone` or `prefix`, `label` or `reason` too long. |
| 429 | `quota_exceeded` | The workspace already holds 500 rules. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |

## Related

- [Conversations](/developers/guides/conversations/)
- [Leads](/developers/guides/leads/)
- [Blocked numbers in the dashboard](/dashboard/blocked-numbers/)
