Do-not-call list

The do-not-call list is a per-workspace set of phone numbers that campaigns will not dial. Add a number and every campaign in the workspace — running, paused or not yet created — skips it. Base URL https://sandbox.voice.miraiminds.co.

This is your suppression list, not the national registry.It suppresses your campaigns on our platform. It is not TRAI’s DND/NCPR register, we do not scrub against that register for you, and having a number on this list is not a substitute for the consent and DND obligations that sit with the business placing the calls. See India calling rules.

How suppression works

Numbers are checked at dial time, in the same database statement that hands contacts to the dialler. Three consequences worth knowing:

Late additions work. A number added while a campaign is running is suppressed from that moment on, even though it was uploaded in the original list.
Suppression is not deletion. The contact stays in the campaign with status: "suppressed" and shows up in the report, so you can prove the number was uploaded and not called.
Suppressed contacts are never billed. No dial, no minute, no charge.

It does not apply to POST /v2/calls. A direct single call is an explicit instruction to ring one number now; refusing it based on a list would silently swallow transactional calls — a delivery confirmation to a customer who opted out of marketing, say. Check the list yourself before placing single calls if that is the behaviour you want.

The entry object

{
  "object": "dnc_entry",
  "phone": "+919876543210",
  "created_at": "2026-08-10T09:44:12Z"
}

Add a number

POST /v2/dnc

curl -X POST https://sandbox.voice.miraiminds.co/v2/dnc \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+919876543210" }'

201 Created

{ "object": "dnc_entry", "phone": "+919876543210", "added": true }

Adding a number that is already on the list is not an error — you asked for it to be suppressed and it is suppressed. You get 200 OK with "added": false instead of 201:

200 OK — already on the list

{ "object": "dnc_entry", "phone": "+919876543210", "added": false }

Branch on added if you are keeping your own count; branch on nothing at all if you are just making sure. Both answers mean the number will not be dialled.

Status	`error.code`	Cause
`400`	`invalid_request`	`phone` is not E.164 — `+919876543210`, not `9876543210`.
`503`	`campaigns_unavailable`	Campaigns (and with them this list) are not enabled for your workspace.

List numbers

GET /v2/dnc?limit=&cursor=

curl -G https://sandbox.voice.miraiminds.co/v2/dnc \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "limit=100"

200 OK

{
  "data": [
    { "object": "dnc_entry", "phone": "+919876543210", "created_at": "2026-08-10T09:44:12Z" },
    { "object": "dnc_entry", "phone": "+919812345678", "created_at": "2026-08-09T16:02:55Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

Standard pagination: limit 1–100, default 20, and cursor from next_cursor.

Remove a number

DELETE /v2/dnc/{phone}

The number goes in the path, URL-encoded — + becomes %2B.

curl -X DELETE "https://sandbox.voice.miraiminds.co/v2/dnc/%2B919876543210" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content on success. 404 not_found if the number was not on the list.

Removing a number un-suppresses it immediately. Contacts already marked suppressed in a campaign stay marked — that status is a record of a decision already taken — but any future campaign, and any contact not yet claimed, will dial it. Keep an audit trail of who removed what: an opt-out you reversed is the complaint you will be asked about.

Keeping it in sync

The list is a set of numbers, and the operations are idempotent, so the simplest correct integration is also the right one: on every opt-out event in your own system, POST the number. No read-modify-write, no diffing.

def on_opt_out(phone: str) -> None:
    r = httpx.post(f"{API}/v2/dnc", headers=auth, json={"phone": phone}, timeout=30)
    if r.status_code not in (200, 201):
        raise RuntimeError(r.json()["error"]["message"])
    # 201 -> newly added, 200 -> already there. Both mean suppressed.

Three habits worth having:

Suppress on the call, not after the campaign. If your agent hears “stop calling me”, write it to the list from the webhook handler that same minute.
Suppress before you upload. Scrubbing the list you upload and keeping the DNC list current are belt and braces; the DNC list is the one that protects you from the campaign you forgot to scrub.
Never remove in bulk. Removals should be individual, deliberate, and logged with a reason.

Start here

Build

Money

Reference

How suppression works

The entry object

Add a number

List numbers

Remove a number

Keeping it in sync

​How suppression works

​The entry object

​Add a number

​List numbers

​Remove a number

​Keeping it in sync

How suppression works

The entry object

Add a number

List numbers

Remove a number

Keeping it in sync