Open in
Opt-outs
Your organization
The opt-out list holds numbers that asked your organization not to text them, not to call them, or both. ThunderPhone checks it before every outbound text and call:
- Texts to a number opted out of
smsare refused:POST /v1/sms, the agent'ssend_smstool, post-call follow-ups, retries and scheduled texts. - Calls to a number opted out of
callare refused:POST /v1/call, campaigns and scheduled calls. - Adding a number skips the queued scheduled sends
to it on that channel, with status
skippedand reasonopted_out. - Asked on a call. When the person on an outbound call asks not to be
called again, the agent apologizes, ends the call and adds the number to the
list for
call, with sourcecall_request. If they hang up before the agent ends the call, ThunderPhone checks the transcript after the call, on calls that keep a transcript, and adds the number then. This is on for every agent unless you turn it off.
Use these endpoints to keep the list in step with your own CRM's opt-outs.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/opt-outs | List opt-outs |
POST | /v1/opt-outs | Add a number |
DELETE | /v1/opt-outs | Remove a number |
GET / POST | /v1/do-not-call-detection-disable-attestation | Read or record the attestation that lets agents turn detection off |
For the opt-out list itself, authenticate with an organization API key. These endpoints are not available to OAuth clients. In a dashboard session any member can list and add numbers; removing one requires an admin or owner, because it lets your organization contact someone who asked it not to. Organization API keys are not limited by role.
Opt-out object
{
"id": 318,
"number": "+14155550199",
"channel": "sms",
"source": "api",
"source_reference": "api_key:12",
"blocks": true,
"created_at": "2026-11-01T18:02:11.204Z",
"updated_at": "2026-11-01T18:02:11.204Z"
}| Field | Type | Description |
|---|---|---|
id | integer | Id of the row |
number | string | E.164 |
channel | string | sms or call. A number opted out of both has one row for each |
source | string | Where it came from: api, manual (added in the dashboard), carrier, or call_request (the person asked the agent on an outbound call not to be called again). inbound_stop (the person replied STOP) is reserved for inbound SMS support and not recorded yet |
source_reference | string | What added it, such as api_key:<id>, user:<id>, sms:<message id> for a carrier refusal, call:<call id> for a request on a call, or call:<call id>:post_call for one found in the transcript after the call |
blocks | boolean | Whether ThunderPhone refuses texts or calls for this row. false for carrier rows |
created_at, updated_at | timestamp | ISO 8601 UTC |
Carrier opt-outs
When Twilio or Telnyx refuses a text because the recipient opted out with the
carrier (error code recipient_opted_out), ThunderPhone records a carrier
row for that number. The carrier enforces these itself, so a carrier row is
recorded but not enforced by ThunderPhone (blocks: false): it skips the
scheduled texts already queued to that number, but new texts are passed to the
carrier as usual. That way a person who opts back in with the carrier, for
example by texting START, is not kept blocked here. A carrier row is removed
when the carrier next accepts a text to that number.
Adding the same number through the API or dashboard turns a carrier row into
a blocking one.
List opt-outs
curl 'https://api.thunderphone.com/v1/opt-outs?channel=sms' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"| Parameter | Description |
|---|---|
number | One number, in any format the API can read as a phone number |
channel | sms or call |
source | api, manual, carrier, inbound_stop or call_request |
limit | 1–500, default 50 |
offset | Default 0 |
Results are newest first.
{
"count": 1,
"results": [
{
"id": 318,
"number": "+14155550199",
"channel": "sms",
"source": "api",
"source_reference": "api_key:12",
"blocks": true,
"created_at": "2026-11-01T18:02:11.204Z",
"updated_at": "2026-11-01T18:02:11.204Z"
}
]
}Add a number
curl -X POST https://api.thunderphone.com/v1/opt-outs \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"number": "+14155550199", "channel": "both"}'| Field | Type | Required | Description |
|---|---|---|---|
number | string | yes | The number, E.164 |
channel | string | no | sms, call or both (default) |
Returns the number's row for each channel, 201 Created when any row is new
and 200 OK when the number was already on the list:
{
"results": [
{ "id": 318, "number": "+14155550199", "channel": "sms", "source": "api", "source_reference": "api_key:12", "blocks": true, "created_at": "2026-11-01T18:02:11.204Z", "updated_at": "2026-11-01T18:02:11.204Z" },
{ "id": 319, "number": "+14155550199", "channel": "call", "source": "api", "source_reference": "api_key:12", "blocks": true, "created_at": "2026-11-01T18:02:11.204Z", "updated_at": "2026-11-01T18:02:11.204Z" }
]
}A number that is not a valid phone number returns 400 invalid_number.
Remove a number
curl -X DELETE 'https://api.thunderphone.com/v1/opt-outs?number=%2B14155550199&channel=sms' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"number is required; channel is sms, call or both (default). Remove a
number only when the person has opted back in.
{ "deleted": 1 }deleted is the number of rows removed, 0 when the number was not on the
list.
Turning detection off
An agent's do_not_call_detection_enabled setting controls the
Asked on a call behavior above. It is true by default. Before any agent
can set it to false, an organization admin must record an attestation that
your organization takes responsibility for do-not-call and opt-out compliance
on those agents' calls. In Zeus, turning off an agent's Stop-calling
requests setting shows the statement to agree to.
GET /v1/do-not-call-detection-disable-attestation ·
POST /v1/do-not-call-detection-disable-attestation
GET returns the current text_version, the English statement
(statement_en) and its statement_sha256, and whether your organization
has an active attestation (attested, attestation).
POST takes accepted: true, the text_version and statement_sha256 from
GET, and an optional display locale (default en; the English statement
governs). It returns 201 with the attestation, or 200 with the existing
one.
Without an active attestation, saving, publishing or creating an agent with
do_not_call_detection_enabled: false returns 400, unless the agent already
has it off. If ThunderPhone suspends or revokes the attestation, detection comes
back on for every agent until a new one is recorded, and those agents carry the
do_not_call_detection_off_without_attestation warning. Turning detection back on never needs one. Numbers
already on your opt-out list stay blocked either way.
| Status | Condition |
|---|---|
201 | Attestation recorded (POST) |
200 | Your organization already has an active attestation (POST) |
400 | accepted was not true, locale is blank, text_version is not current, or statement_sha256 does not match the statement |
403 | API key, or the caller is not an organization admin (POST) |
What a refusal looks like
| Request | Response |
|---|---|
POST /v1/sms | 409 with error.code contact_opted_out |
POST /v1/scheduled | 409 with error.code contact_opted_out |
POST /v1/call | 400 destination_not_allowed with reason contact_opted_out |
| Campaign contact | The contact fails; the campaign keeps running |
| Scheduled send already queued | skipped with status_reason opted_out |