# Create a WhatsApp suppression

`POST /v1/whatsapp/suppressions`

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.

## Code samples

**TypeScript**

```ts
// Omit waba to block the address for the whole workspace, whichever account
// sends. With it, your other accounts keep reaching them, and the same
// address for two accounts is two records.
const suppression = await bird.whatsapp.suppressions.add({
  address: "+15550001234",
  waba: "102290129340398",
});
console.log(suppression.id, suppression.applies_to);
```

Examples: [TypeScript](/docs/api/reference/create-whatsapp-suppression.ts.md) · [Python](/docs/api/reference/create-whatsapp-suppression.py.md) · [Go](/docs/api/reference/create-whatsapp-suppression.go.md) · [PHP](/docs/api/reference/create-whatsapp-suppression.php.md) · [CLI](/docs/api/reference/create-whatsapp-suppression.cli.md) · [MCP](/docs/api/reference/create-whatsapp-suppression.mcp.md) · [cURL](/docs/api/reference/create-whatsapp-suppression.curl.md)

## Example response `200`

```json
{
  "id": "was_01krdgeqcxet5s7t44vh8rt9mg",
  "address": "+5511977670804",
  "waba": null,
  "reason": "manual",
  "origin": "api_key",
  "applies_to": "all",
  "source_whatsapp_id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
  "ended_reason": "api_key"
}
```

## Request body

- `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 body

- `id` (string, required): Unique identifier for the suppression record.
- `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` (nullable string): 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.

  Possible values (may grow over time): `manual`
- `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.

  Possible values (may grow over time): `api_key`, `user`
- `applies_to` (string, required)

  Blocking policy. `all` blocks every message category. Treat an unrecognized value as blocking.

  Possible values (may grow over time): `all`
- `source_whatsapp_id` (string): ID of the WhatsApp message that caused this address to be suppressed, when the suppression was created automatically. Omitted for addresses added manually.
- `ended_at` (nullable string): When this stopped applying. Null while it is still stopping messages, which is the case for every record in the list.
- `ended_reason` (nullable string)

  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.

  Possible values (may grow over time): `api_key`, `user`
- `created_at` (string, required): When the suppression was created.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)