POST /api/public/v1/suppressions

Adds phone numbers to your organization's do-not-call list. Use it to sync the opt-outs your own systems receive — a reply to an email, a web form, a complaint to your call centre — so that nobody on this platform calls those numbers on your behalf.

Property	Value
Method	POST
Path	/api/public/v1/suppressions
Scopes	contact:write
Org kind	Buyer organizations only
Cost	10 rate-limit tokens
Numbers	1–1000 per request
Retries	Safe without a key; idempotency-key replays the counts

Nothing added can be removed. The list has no delete route, here or in the dashboard. A number stays on it for five years after the latest time it was added, and adding it again restarts that period. Send only numbers whose owners asked not to be called.

The list is write-only through the API. There is no route that reads it or checks a number against it: a key cannot be used to learn who has opted out. Calls placed through the platform are checked against it automatically.

Request

{
  "numbers": ["0821234567", "+27 83 765 4321"],
  "note": "Unsubscribed via our website"
}

Field	Type	Required	Notes
numbers	string[]	Yes	1–1000, each ≤ 40 characters. A national number is read as South African.
note	string	No	≤ 500 characters, shown beside the entry in the dashboard.

Numbers are normalised to E.164 before they are stored, so 082 123 4567, 0027821234567 and +27821234567 are the same number. A number that is not valid for its country is reported, not fatal: the rest of the request is still added.

Response

200, with how the numbers landed:

{
  "data": {
    "added": 1,
    "already": 1,
    "invalid": []
  }
}

Field	Type	Meaning
added	number	Numbers that were not on the list before this request.
already	number	Numbers that were already on it. Their five years restart from now.
invalid	string[]	Entries that are not a valid phone number, as you sent them. Nothing was added.

Errors

Status	Code	When
400	INVALID_INPUT	No numbers, more than 1000, or an entry over 40 chars.
403	FORBIDDEN	The key lacks contact:write, or the org is not a buyer.
429	TOO_MANY_REQUESTS	The key's rate limit is spent. See rate limits.

See errors for the envelope.

Source

Value	Source
Request and response shapes	SuppressionSchema.api, SuppressionSchema.api_result in src/lib/schema/suppression/suppression.schema.ts
Per-request bound, cost	SUPPRESSION.ADD_MAX, SUPPRESSION.API_COST in src/lib/const/suppression.const.ts
Retention	SUPPRESSION.RETENTION