---
title: "Add suppression entry"
method: POST
path: "/api/v1/suppression"
tags: ["suppression"]
---

# Add suppression entry

`POST /api/v1/suppression`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/suppression`
- Auth: HTTP bearer

Add a do-not-contact entry. Idempotent: re-adding returns the existing entry.

Use channel "all" to block every channel for the identifier; `channel` is one of all, whatsapp, sms, email.

`reason` is normalized on write: `manual` is stored as `manual_add` and `complaint` as `spam_report`, so the response reason can differ from what you sent. Accepted reasons: manual_add, stop_keyword, unsubscribe_link, preference_center, csv_import, bounce, spam_report.

`topic` (all | marketing | transactional) scopes the block and defaults to `all`; hard reasons (stop_keyword / bounce / spam_report) always force `all`, and unsubscribe_link / preference_center force `marketing`.

Re-adding an identifier that is already suppressed returns the existing row with `already_present: true` (a 200, not a 201), so the call stays safe to retry.

## Request body

- object
  - `identifier` string, required
  - `channel` 'all' | 'whatsapp' | 'sms' | 'email', required
  - `topic` 'all' | 'marketing' | 'transactional'
  - `reason` 'manual' | 'manual_add' | 'stop_keyword' | 'csv_import' | 'bounce' | 'complaint' | 'spam_report' | 'unsubscribe_link' | 'preference_center'
  - `reason_detail` string
  - `business_id` string, uuid

## Response `201`

Success

- object
  - `entry` object, required
    - `id` string, uuid, required
    - `business_id` string, nullable, required
    - `identifier` string, required
    - `channel` 'all' | 'whatsapp' | 'sms' | 'email' | 'telegram', required
    - `topic` string, required
    - `reason` string, required
    - `reason_detail` string, nullable, required
    - `added_by` string, nullable, required
    - `created_at` string, date-time, required
  - `already_present` boolean, required
  - `request_id` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)