Block a number or a dial prefix

POST

/blocked-contacts

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

• Production

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.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

kind

required

string

Allowed values: number prefix

phone

For kind: number. Any international format, e.g. +33 6 12 34 56 78.

string

prefix

For kind: prefix. 1 to 4 digits, e.g. +91 or 91.

string

label

string

<= 80 characters

reason

string

<= 500 characters

Example

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

Responses

201

The rule

Media typeapplication/json

object

data

object

id

string

kind

string

Allowed values: number prefix

value

The bare digits of the number (or a masked WhatsApp id), or the dial code.

string

phone

E.164 form for kind: number when the value is a real phone; null otherwise.

string | null

label

string | null

reason

string | null

campaign_id

null = team-wide (every rule created through the API); a campaign slug when the dashboard scoped it.

string | null

created_at

string format: date-time

Example

{
  "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

Media typeapplication/json

object

error

object

code

string

message

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

The key lacks the required scope

Media typeapplication/json

object

error

object

code

string

message

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

This number or prefix is already blocked

Media typeapplication/json

object

error

object

code

string

message

string

Example

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

422

Invalid kind, phone, prefix, label or reason

Media typeapplication/json

object

error

object

code

string

message

string

Example

{
  "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

Media typeapplication/json

object

error

object

code

string

message

string

Example

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