ThunderPhone v3 is live.Self-serve, from 2¢/min.Read the announcement

Phone Numbers

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 sms are refused: POST /v1/sms, the agent's send_sms tool, post-call follow-ups, retries and scheduled texts.
  • Calls to a number opted out of call are refused: POST /v1/call, campaigns and scheduled calls.
  • Adding a number skips the queued scheduled sends to it on that channel, with status skipped and reason opted_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 source call_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

MethodPathDescription
GET/v1/opt-outsList opt-outs
POST/v1/opt-outsAdd a number
DELETE/v1/opt-outsRemove a number
GET / POST/v1/do-not-call-detection-disable-attestationRead 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"
}
FieldTypeDescription
idintegerId of the row
numberstringE.164
channelstringsms or call. A number opted out of both has one row for each
sourcestringWhere 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_referencestringWhat 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
blocksbooleanWhether ThunderPhone refuses texts or calls for this row. false for carrier rows
created_at, updated_attimestampISO 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"
ParameterDescription
numberOne number, in any format the API can read as a phone number
channelsms or call
sourceapi, manual, carrier, inbound_stop or call_request
limit1–500, default 50
offsetDefault 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"}'
FieldTypeRequiredDescription
numberstringyesThe number, E.164
channelstringnosms, 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.

StatusCondition
201Attestation recorded (POST)
200Your organization already has an active attestation (POST)
400accepted was not true, locale is blank, text_version is not current, or statement_sha256 does not match the statement
403API key, or the caller is not an organization admin (POST)

What a refusal looks like

RequestResponse
POST /v1/sms409 with error.code contact_opted_out
POST /v1/scheduled409 with error.code contact_opted_out
POST /v1/call400 destination_not_allowed with reason contact_opted_out
Campaign contactThe contact fails; the campaign keeps running
Scheduled send already queuedskipped with status_reason opted_out