Tone docs
API referenceCompliance

Numbers on the Do-Not-Call list

Your own suppression list — the only list the gate hard-blocks on. Search accepts whatever someone types: +91 98765 43210, 09876543210 and 4321 all work.

Open in ClaudeOpen in ChatGPTView as Markdown

Requires the read scope. A key with less gets 403 insufficient_scope.

GET
/v1/dnc

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Query Parameters

limit?integer

How many results to return. 1-100, defaulting to 25.

Range1 <= value <= 100
Default25
cursor?string

Opaque page cursor — pass meta.pagination.cursor from the previous response to fetch the next page. Its contents are an implementation detail; do not parse or construct one.

Length1 <= length
source?string

Only entries added this way. Open set — handle an unrecognised value rather than throwing. Today: manual, csv, api, caller_request, complaint, carrier_rejection.

Value in

  • "manual"
  • "csv"
  • "api"
  • "caller_request"
  • "complaint"
  • "carrier_rejection"
status?string

Whether to include entries whose 90-day lockout has already elapsed. Open set — handle an unrecognised value rather than throwing. Today: all, active, permanent, lockout, lapsed, removed.

Default"all"

Value in

  • "all"
  • "active"
  • "permanent"
  • "lockout"
  • "lapsed"
  • "removed"
search?string

Digits to find. A full number matches exactly, a fragment matches anywhere in the number. Deliberately forgiving about formatting — +91 98765 43210, 09876543210 and 4321 all work.

Lengthlength <= 20

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/dnc"
{  "data": [    {      "createdAt": "2026-08-25T09:14:22Z",      "e164": "+919876543210",      "expiresAt": "2026-11-23T09:14:22Z",      "id": "8814",      "reason": "Asked to be removed during a call on 2026-08-20.",      "removedAt": null,      "removedReason": null,      "source": "manual",      "sourceCallId": null    }  ]}
Was this page helpful?

Suppress many numbers at once (CSV upload)

Up to 1,000 per request, as one transaction — it either all lands or none of it does. This is how you bring an existing suppression list with you.

Deprecated — lifting a suppression now requires the dashboard

⚠️ Always refuses. Lifting a suppression is a deliberate, reasoned act: it now requires a dashboard session and a written justification (POST /v1/dnc/{id}/remove, session-only), and is recorded in the audit trail. API keys can ADD suppressions — an opt-out must land within seconds — but can no longer silently make an opted-out number callable again.