---
title: "Create a WhatsApp suppression"
method: POST
path: "/v1/whatsapp/suppressions"
tags: ["whatsapp-suppressions"]
---

# Create a WhatsApp suppression

`POST /v1/whatsapp/suppressions`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/whatsapp/suppressions`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Manually adds a WhatsApp address to the suppression list with reason `manual`. If the address is already suppressed, the API returns `200` with the existing record.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- WhatsAppSuppressionCreate
  - `address` string, required: WhatsApp address to suppress. For a phone number, supply canonical E.164 with a leading plus sign, such as `+5511977670804`. A value that is not a valid phone number returns a `422`.
  - `waba` string: Limit the suppression to messages sent from this WhatsApp Business Account, identified by its WhatsApp-issued account ID. Omit it to block the address for the whole workspace, whichever account sends.

## Response `200`

Address was already suppressed. Existing record returned.

- WhatsAppSuppression: One period during which an address is suppressed: when it started and, once it is over, what ended it. An address suppressed, ended and suppressed again has two of these on record rather than one current state. The list returns the periods in force; fetch one by ID to read one that has ended.
  - `id` string, required
  - `address` string, required: The suppressed WhatsApp address. For a phone number this is canonical E.164 with a leading plus sign, such as `+5511977670804`.
  - `waba` string, nullable: The WhatsApp Business Account the suppression is limited to, identified by its WhatsApp-issued account ID, or null when it covers the whole workspace.
  - `reason` string, required: Why the address is suppressed. `manual` means it was added directly rather than created automatically from a delivery outcome. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
  - `origin` string, required: How the suppression came to exist: `api_key` (added through the API with an API key) or `user` (added by a user in the dashboard). This list grows over time, so treat an unknown value as informational rather than rejecting the record.
  - `applies_to` string, required: Blocking policy. `all` blocks every message category. Treat an unrecognized value as blocking.
  - `source_whatsapp_id` string
  - `ended_at` string, date-time, nullable: When this stopped applying. Null while it is still stopping messages, which is the case for every record in the list.
  - `ended_reason` string, nullable: What ended it: `api_key` (deleted through the API with an API key) or `user` (deleted by a user in the dashboard). Null while it is still stopping messages. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
  - `created_at` string, date-time, required: When the suppression was created.

## Other responses

- `201`: Suppression created.
- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)