Taalk DNC API — Check if a phone is on Do Not Call
Purpose: Quickly determine whether a phone number should be blocked from outbound contact based on local or global Do Not Call (DNC) lists. Interactive docs: Use the live Swagger UI here: https://lets.taalk.ai/doc/swagger Endpoint: GET /dnc/{phone}
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.