Taalk DNC API — Check if a phone is on Do Not Call

Overview

The GET /dnc/{phone} endpoint returns whether a phone number appears in either your local DNC list or the global DNC list. If the number exists in any DNC source, it is considered blocked.

Blocked logic: blocked = in_local_dnc OR in_global_dnc
Stateless: Multiple checks on the same number return the same result unless your DNC lists change.

Request

HTTP

GET /dnc/{phone}?db={dataSourceId}

Path parameters

phone (string, required) — The phone number to check.
- Format recommended: E.164 (e.g., +17041234567). Non‑E.164 inputs are accepted but may be normalized by your data source.

Query parameters

db (string, optional) — Data source identifier.
- Use when your API key has access to multiple data sources/tenants.
- Example: db=free

Headers

Authorization: Bearer <token> (if your environment requires auth for this route)
Accept: application/json

Response

200 OK

Returns a JSON object with a payload map of <phone>: <status>.

Status: 1 = blocked (in local or global DNC), 0 = not blocked.

Example

{
  "payload": {
    "704123456": 1
  }
}

Notes

• The key inside payload will mirror the normalized phone string stored/checked by your data source.

• If your request used E.164, expect the same E.164 in the key when supported by the data source.

Error responses

Status	When it happens	Shape
400 Bad Request	Missing/invalid phone or malformed number	{ "error": "invalid_phone" }
401 Unauthorized	Missing/invalid credentials (if required)	{ "error": "unauthorized" }
403 Forbidden	Authenticated but not allowed for this db	{ "error": "forbidden" }
404 Not Found	Unknown db (data source id)	{ "error": "db_not_found" }
429 Too Many Requests	Rate-limited	{ "error": "rate_limited" }
5xx	Upstream/data-source errors	{ "error": "server_error" }

(Exact shapes may vary by deployment; check the Swagger “Responses” for your environment.)

Examples

cURL

curl -X GET \
  "https://api.taalk.ai/api/dnc/+17041234567?db=free" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

JavaScript (fetch)

const res = await fetch(
  "https://api.taalk.ai/api/dnc/+17041234567?db=free",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "Accept": "application/json"
    }
  }
);
const data = await res.json();
const blocked = data.payload["+17041234567"] === 1;

Python (requests)

import requests

url = "https://api.taalk.ai/api/dnc/+17041234567"
params = {"db": "free"}
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
}

r = requests.get(url, params=params, headers=headers, timeout=10)
r.raise_for_status()
blocked = r.json()["payload"]["+17041234567"] == 1

Implementation guidance

Normalization: Always send E.164 where possible. If you must send local formats, ensure your data source supports normalization rules that match your dialing plan.
Single source of truth: If you manage both local and global lists, remember that any match blocks the call. Use this endpoint before initiating calls or texts.
Caching: You may cache negative results (not blocked) briefly (e.g., 5–15 minutes). Do not long‑cache positive (blocked) results if your operations frequently grant exceptions or remove numbers.
Latency & retries: Treat the check as a lightweight read. If you retry on transient 5xx, use exponential backoff.
Auditing: Log phone, db, blocked result, and the decision point in your outbound flow for compliance traceability.
Rate limits: Respect 429 responses. Back off and retry after the window indicated by Retry-After (if provided).

Common questions

Q: What does the integer value mean?

1 = the number is on DNC (blocked). 0 = not on DNC.

Q: Which list “wins” if local says no and global says yes?

Global DNC wins; any positive match blocks the number.

Q: Do I need the db parameter?

Only if your credentials span multiple data sources/tenants. Otherwise omit it.

Q: Can I check multiple numbers at once?

This endpoint checks a single phone per call. If you need bulk checks, contact support or batch on the client side.

Try it now

Head to the Swagger UI and use Try it out to make a live request with your credentials:

https://api.taalk.ai/doc/swagger

Changelog

2025‑08‑10: Clarified response semantics (1 = blocked, 0 = not blocked), added examples, error table, and best practices. Linked to Swagger UI.