Copy page

Guides

Manage the DNC Directory

This guide walks through every DNC operation you'll do from the API. For the conceptual model see DNC Directory.

Check a number before dialing

Code
curl https://api.neuratel.ai/v1/dnc/check?phone=%2B12125551234 \
  -H "Authorization: Bearer $NEURATEL_API_KEY"

Code
{
  "phone": "+12125551234",
  "blocked": true,
  "source": "platform",
  "added_at": "2026-04-12T09:31:00Z",
  "reason": "Federal DNC registry"
}

Code
from neuratelai import NeuratelAI
client = NeuratelAI()

result = client.dnc.check("+12125551234")
if result["blocked"]:
    print(f"Blocked by {result['source']}: {result['reason']}")

Code
import { NeuratelAI } from "@neuratelai/sdk";
const client = new NeuratelAI();

const result = await client.dnc.check("+12125551234");
if (result.blocked) console.log(`Blocked by ${result.source}`);

Add a number to your org's DNC list

Code
client.dnc.add_entry(
    phone="+12125551234",
    reason="Customer requested removal via support ticket #1234",
)

Code
await client.dnc.addEntry({
  phone: "+12125551234",
  reason: "Customer requested removal via support ticket #1234",
});

List entries visible to your org

By default returns entries from all sources. Filter to see only org-uploaded:

Code
entries = client.dnc.list_entries(source="org_upload", limit=100)
for e in entries["results"]:
    print(e["phone"], e["source"], e["added_at"])

Remove an org-uploaded entry

Only org_upload entries can be removed. The delete is soft (audit-preserved):

Code
client.dnc.delete_entry("dnc_01HX...")

platform and inbound_optout entries cannot be deleted by org admins.

Toggle protection settings

Code
# Read current settings
settings = client.dnc.get_settings()
print(settings)
# {"protection_enabled": True, "auto_add_inbound_optouts": True}

# Disable auto-add of inbound STOP replies (advanced — handle opt-outs in your own app)
client.dnc.update_settings(auto_add_inbound_optouts=False)

The two canonical settings:

Field	Default	Effect
protection_enabled	true	When false, DNC checks log but do not block outbound calls. Use only for testing.
auto_add_inbound_optouts	true	When false, your application must add inbound opt-outs manually.

Common patterns

Pre-flight a campaign. Before starting an outbound campaign, the platform automatically DNC-checks each contact at dial time. You don't need to pre-check — but if you want to surface the dropped count in your UI before launching, query /dnc/check for each number client-side.

Honor compliance imports. Bulk-import a regulator's DNC export by looping add_entry with reason="Imported from {regulator name} {date}". The MCP server's dnc_add_entry tool can be invoked from an LLM agent if your import flow is conversational.

Detect false positives. If a contact you expect to dial is reported as blocked, dnc.check() returns source — platform entries cannot be overridden by org admins, so contact your account team if mis-listed.

Cost

DNC checks (including pre-call enforcement on every outbound dial), entry add/delete, and STOP auto-detection are included with the platform — no additional fees.

Related

• DNC Directory concept
• Outbound campaigns
• Production checklist