# Block a number or a dial prefix

`POST https://app.whatsetter.com/api/v1/blocked-contacts`

Silences the AI agent for one number (`kind: number` + `phone`, any
international format) or a whole dial code (`kind: prefix` + `prefix`,
1 to 4 digits, with or without `+`). Their messages still reach the
inbox; the agent never replies or follows up. Rules are team-wide.
`label` (≤ 80) and `reason` (≤ 500) are optional. A workspace holds at
most 500 rules. Requires scope `blocklist:manage`.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | number \| prefix | yes |  |
| `phone` | string | no | For `kind: number`. Any international format, e.g. `+33 6 12 34 56 78`. |
| `prefix` | string | no | For `kind: prefix`. 1 to 4 digits, e.g. `+91` or `91`. |
| `label` | string | no |  |
| `reason` | string | no |  |

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

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/blocked-contacts' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"kind":"prefix","prefix":"+91","label":"India","reason":"Out of market"}'
```

## Responses

### 201: The rule

```json
{
  "data": {
    "id": "68f1a0b1c2d3e4f5a6b7c8da",
    "kind": "prefix",
    "value": "91",
    "phone": null,
    "label": "India",
    "reason": "Out of market",
    "campaign_id": null,
    "created_at": "2026-09-15T12:01:00.000Z"
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: The key lacks the required scope (`insufficient_scope`), the plan does not have this part of the API (`not_in_plan`), or Instagram is not enabled on the workspace (`instagram_not_enabled`, Instagram routes)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: This number or prefix is already blocked

```json
{
  "error": {
    "code": "already_blocked",
    "message": "The +91 prefix is already blocked in this workspace."
  }
}
```

### 422: Invalid kind, phone, prefix, label or reason

```json
{
  "error": {
    "code": "validation_error",
    "message": "\"prefix\" must be a dial code of 1 to 4 digits, e.g. +91."
  }
}
```

### 429: The workspace already holds 500 rules

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "This workspace already has 500 blocked entries. Remove some first."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/createblockedcontact/
