API Developers — DNCSweeper

Overview

The DNCSweeper Check API lets you verify whether a phone number is on the Do Not Call registry. It is built for fast, reliable lookups so you can keep outbound workflows compliant.

Access requires an active paid plan and API credentials from Settings → Connect API. All responses are returned as JSON.

CRM import and webhooks are separate. This page covers real-time phone checks and outbound batch.completed webhooks. Pushing cleaned contacts into Texttorrent uses the dashboard’s Import to your CRM flow — not the Check API.

Authentication

Authentication uses your Auth Token from Settings → Connect API as the API key. Send it in the request header (X-API-KEY) or as a query parameter (apikey).

Your Account SID identifies the account. When your CRM stores both values, you may also send X-API-SID; if present it must match the token’s account.

Header

X-API-KEY: YOUR_AUTH_TOKEN

Query string

?apikey=YOUR_AUTH_TOKEN

Endpoint

GET /api/v1/check/?apikey={API_KEY}&phone={PHONE_NUMBER}

Base URL: https://dncsweeper.com/api/v1

Query parameters

Parameter	Type	Description
`apikey`	string	Required unless provided in the `X-API-KEY` header. Your Connect API Auth Token.
`phone`	string	Required. Phone number to check (10 digits recommended).

Responses

Success response

{
  "success": true,
  "phone": "9254047311",
  "is_dnc": true,
  "status": "DNC",
  "source": "registry",
  "timestamp": "2025-12-31 18:10:58"
}

Field	Description
`success`	Indicates the request was processed successfully
`phone`	The normalized phone number that was checked
`is_dnc`	Boolean indicating if the number is on the DNC list
`status`	Human-readable status (`DNC` or `NOT DNC`)
`source`	`registry` for a live lookup, or `cache` when a recent result was reused
`timestamp`	Server time when the lookup completed

Missing parameters

{
  "error": "Missing parameters"
}

Cause: missing X-API-KEY / apikey or phone.

Invalid API key

{
  "error": "Invalid API Key"
}

Cause: API key is incorrect or revoked.

Invalid phone number

{
  "error": "Invalid phone number"
}

Accepted format: digits only (for example 9254047311). US numbers are normalized automatically.

Example request

curl -X GET "https://dncsweeper.com/api/v1/check?phone=9254047311" \
  -H "X-API-KEY: YOUR_AUTH_TOKEN"

$response = Http::withHeaders([
    'X-API-KEY' => $authToken,
])->get('https://dncsweeper.com/api/v1/check', [
    'phone' => '9254047311',
]);

$data = $response->json();
// $data['is_dnc'], $data['status']

const response = await fetch(
  'https://dncsweeper.com/api/v1/check?phone=9254047311',
  {
    headers: {
      'X-API-KEY': process.env.DNCSWEEPER_AUTH_TOKEN,
      Accept: 'application/json',
    },
  },
);

const data = await response.json();
// data.is_dnc, data.status

Error codes

Status	Meaning
`200`	Success
`400`	Missing or invalid parameters
`401`	Invalid API key
`403`	Active subscription required
`500`	Server error

Webhooks

Configure an HTTPS endpoint under Settings → Webhooks. When a batch finishes scrubbing, DNCSweeper POSTs a signed JSON payload to that URL. Works with any receiver — your backend, dialer middleware, or an automation tool.

Event

batch.completed — sent once per finished batch.

Headers

Content-Type: application/json
User-Agent: DNCSweeper-Webhooks/1.0
X-DNCSweeper-Event: batch.completed
X-DNCSweeper-Delivery: {delivery_id}
X-DNCSweeper-Signature: sha256={hmac_hex}

Verify the signature as HMAC-SHA256 of the raw request body using your webhook signing secret from Settings. The header value is prefixed with sha256=.

Example payload

{
  "id": "9f3c…",
  "event": "batch.completed",
  "created_at": "2026-08-07T02:00:00+00:00",
  "data": {
    "batch_id": 42,
    "filename": "leads.csv",
    "status": "completed",
    "total": 1000,
    "processed": 1000,
    "dnc_count": 120,
    "clean_count": 850,
    "invalid_count": 20,
    "failed_count": 10,
    "started_at": "2026-08-07T01:55:00+00:00",
    "completed_at": "2026-08-07T02:00:00+00:00",
    "export_url": "https://your-domain/batches/42/export"
  }
}

Use Send test event in Settings to verify your endpoint before relying on production batches. Recent deliveries (success/fail and HTTP status) appear on the same page.

Notes

Phone numbers are normalized automatically when possible (US 10-digit NANP).
Invalid requests are rejected immediately.
An active subscription is required for Check API calls (HTTP 403 otherwise).
Successful lookups may be served from a short-lived cache; see the source field.
Regenerating credentials in Settings immediately invalidates the previous Auth Token.
Webhooks are configured per account in Settings → Webhooks, not via the Check API.

DNC Check API