> ## Documentation Index
> Fetch the complete documentation index at: https://docs.miraiminds.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Do-not-call list
> Your workspace's own suppression list of numbers that campaigns will never dial.
The **do-not-call list** is a per-workspace set of phone numbers that
[campaigns](/v2/campaigns) will not dial. Once you add a number, every campaign
in the workspace skips it, whether the campaign is running, paused or not yet
created.
Base URL `https://sandbox.voice.miraiminds.co`.
**This is your suppression list, not the national registry.**
It suppresses numbers for *your* campaigns on *our* platform. It is separate
from TRAI's DND/NCPR register, and we do not scrub against that register for
you. The consent and DND obligations sit with the business placing the calls,
and putting a number on this list does not meet them. See
[India calling rules](/v2/limits#india-calling-rules).
## How suppression works
We check numbers **at dial time**, in the same database statement that hands
contacts to the dialler. This has three consequences:
* **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"`](/v2/campaigns#contact-statuses) and shows up in the
report, so you can prove the number was uploaded and not called.
* **Suppressed contacts are never billed.** We never dial them, so there are
no minutes to charge.
The list does **not** apply to [`POST /v2/calls`](/v2/calls#create-a-call). A
direct single call is an explicit instruction to ring one number now. If we
refused it because the number is on the list, transactional calls would be
dropped without any notice, such as a delivery confirmation to a customer who
opted out of marketing. If you want single calls checked as well, check the
list yourself before you place them.
## The entry object
```json theme={null}
{
"object": "dnc_entry",
"phone": "+919876543210",
"created_at": "2026-08-10T09:44:12Z"
}
```
***
## Add a number
```http theme={null}
POST /v2/dnc
```
```bash theme={null}
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" }'
```
```json title="201 Created" theme={null}
{ "object": "dnc_entry", "phone": "+919876543210", "added": true }
```
Adding a number that is already on the list is **not an error**, because the
number is already suppressed. You get `200 OK` with `"added": false` instead of
`201`:
```json title="200 OK — already on the list" theme={null}
{ "object": "dnc_entry", "phone": "+919876543210", "added": false }
```
If you keep your own count, branch on `added`. If you only need the number
suppressed, you can ignore it. Both responses mean the number will not be
dialled.
| Status | `error.code` | Cause |
| :- | :- | :- |
| `400` | `invalid_request` | `phone` is not E.164. Send `+919876543210`, not `9876543210`. |
| `503` | `campaigns_unavailable` | Campaigns (and with them this list) are not enabled for your workspace. |
***
## List numbers
```http theme={null}
GET /v2/dnc?limit=&cursor=
```
```bash theme={null}
curl -G https://sandbox.voice.miraiminds.co/v2/dnc \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
--data-urlencode "limit=100"
```
```json title="200 OK" theme={null}
{
"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
}
```
This route uses standard [pagination](/v2/overview#pagination): `limit` from 1
to 100 (default 20), and `cursor` from `next_cursor`.
***
## Remove a number
```http theme={null}
DELETE /v2/dnc/{phone}
```
The number goes in the path, URL-encoded, so `+` becomes `%2B`.
```bash theme={null}
curl -X DELETE "https://sandbox.voice.miraiminds.co/v2/dnc/%2B919876543210" \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
A successful delete returns `204 No Content`. If the number was not on the
list, you get `404 not_found`.
**Removing a number un-suppresses it immediately.** Contacts already marked
`suppressed` in a campaign stay marked, because that status records a decision
already taken. Any future campaign, and any contact not yet claimed, will dial
the number. Keep an audit trail of who removed each number. If a reversed
opt-out leads to a complaint, you will be asked about it.
***
## Keeping it in sync
The list is a set of numbers and the operations are idempotent, so the simplest
integration is also correct: on every opt-out event in your own system, `POST`
the number. You don't need to read the list first or diff it against yours.
```python theme={null}
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.
```
We recommend three habits:
1. **Suppress on the call, not after the campaign.** If your agent hears "stop
calling me", add the number to the list from the webhook handler that same
minute.
2. **Suppress before you upload.** Scrub each contact list before you upload
it, *and* keep the DNC list current. If you forget to scrub a campaign's
list, the DNC list still keeps those numbers from being dialled.
3. **Never remove in bulk.** Remove numbers one at a time, deliberately, and
log a reason for each removal.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.