DialCode API
Send a phone number (or up to 10,000 in one batch request), get back whether it's real, which country and area it's from, what line type it is, and whether its prefix is currently associated with reported scams. JSON in, JSON out.
Authentication
Every request needs an X-Api-Key header. Get a free key at /login - no credit card, no forms beyond an email address for the magic link.
X-Api-Key: dc_your_key
Requests without a valid key get 401 with {"error": "invalid_api_key"}.
Endpoint
GET /v1/phone/{number}
Many numbers? Use the batch endpoint - up to 10,000 per request.
{number} is any phone number in international format. The leading + works as-is in the URL path - no encoding needed (%2B also accepted if your HTTP client encodes it). Numbers sent without the + (e.g. 13214991734) are parsed as international automatically. Input under 4 digits returns 400 unparseable_number. Numbers that don't parse to a real dialing plan return a valid: false result rather than an error - with a hint field saying what would resolve them.
National-format numbers: ?country=
A number written the way people write it locally - 8663982896, 866-398-2896, (866) 398-2896 - carries no country code, so it cannot be resolved on its own. Pass the country and it will be read against that numbering plan:
$ curl "https://dialcode.app/v1/phone/8663982896?country=US" \
-H "X-Api-Key: dc_your_key"
{ "valid": true, "e164": "+18663982896", "country": { "code": "US", ... } }
country takes an ISO 3166-1 alpha-2 code (case-insensitive) and applies to that one lookup. An unknown code returns 400 invalid_country and is not counted as a lookup. The same option exists for CSV uploads in your account, where it applies to every row of the file.
If all your numbers come from one market, set a default country on your key in your account instead: every lookup and upload that names no country is read against it. An explicit ?country= still wins.
When a number still comes back valid: false, reason says which kind of false it is: needs_country means the digits are a real national number somewhere and candidates lists the countries that accept them; not_a_number means no numbering plan does.
$ curl https://dialcode.app/v1/phone/+639171234567 \
-H "X-Api-Key: dc_your_key"
{
"valid": true,
"e164": "+639171234567",
"country": { "code": "PH", "dial_code": "+63", "name": "Philippines", "timezone": "Asia/Manila" },
"formats": { "national": "0917 123 4567", "international": "+63 917 123 4567" },
"carrier": "Globe",
"carrier_details": { "name": "Globe", "legal_name": null, "ocn": null, "type": null, "rate_center": null,
"region": null, "assigned_on": null, "source": "libphonenumber" },
"line_type": "mobile",
"area": { "code": "917", "name": "Manila" },
"risk": {
"scam_risk": "high",
"scam_types": ["wangiri", "romance"],
"advice_url": "https://dialcode.app/scam/63-scam",
"complaints": null,
"signals": []
}
}
Response fields
| Field | Type | Description |
|---|---|---|
valid | boolean | Whether the number parses as a real, dialable number. Satellite and other non-geographic numbers (+881, +883, +800) count as valid. |
e164 | string | null | Normalized E.164 form. Null when valid is false. |
reason | string | Present only when valid is false: needs_country (a real national number, country missing) or not_a_number (no numbering plan accepts it). |
candidates | array of strings | Present only when valid is false: ISO 3166-1 alpha-2 codes the input resolves under, US first then alphabetical. Empty for not_a_number and whenever country was given. |
hint | string | Present only when valid is false: what would make the number resolve, in words. Names the countries to pass when the input looks like a national-format number. |
country.code | string | null | ISO 3166-1 alpha-2 country code (e.g. PH). The whole country object is null for non-geographic numbers (satellite, international networks, universal toll-free). |
country.dial_code | string | null | International dialing code (e.g. +63). |
country.name | string | null | Country name. null for a few valid regions we have no profile for yet (e.g. Guam GU, Jersey JE, Reunion RE); code, dial_code and timezone are still filled. |
country.timezone | string | null | IANA timezone of the country's capital (e.g. Asia/Manila). For countries spanning multiple zones this is the capital's zone, not the number's exact zone. |
formats.national | string | null | Number formatted for domestic dialing (e.g. 0917 123 4567). Null when valid is false. |
formats.international | string | null | Human-readable international format with spacing (e.g. +63 917 123 4567). Use e164 for machine comparison. |
carrier | string | null | Carrier the number range was assigned to, as a brand (e.g. Verizon Wireless, Globe, O2). This is the range holder, not necessarily the current operator - numbers moved via porting keep their original range label. US and Canadian numbers: from the NANPA and CNAC assignment records (thousands block first, then the central office code). Elsewhere: libphonenumber range data, mostly mobile numbers; null for most landlines. Try it on the carrier lookup page. |
carrier_details | object | null | Where carrier came from. name (same as carrier), legal_name (entity in the numbering records, e.g. CELLCO PARTNERSHIP DBA VERIZON WIRELESS - CA), ocn (Operating Company Number), type (mobile, landline, voip, paging or null - the kind of network the carrier runs, known for the large US/Canadian carriers; tells mobile from landline where line_type says fixed_or_mobile), rate_center, region (US state / Canadian province), assigned_on (date), source (nanpa, cnac or libphonenumber). Fields other than name and source are null for libphonenumber. null when carrier is. |
line_type | string | null | Line type: mobile, fixed_line, voip, toll_free, pager and so on. For geographic US/Canada numbers it comes from the network type of the carrier holding the range (at allocation - ported numbers are not detected); fixed_or_mobile when we cannot classify that carrier. |
area.code | string | null | Local area code, when the country has area-code data and one matches. |
area.name | string | null | City / region for the matched area code. |
risk.scam_risk | string | low, medium, high, or unknown. An editorial rating of the number's country code, set by hand (in the +1 zone the country comes from the area code, so +1-876 Jamaica is rated on its own). It is not a score for this number and is not computed from complaint counts (FTC and FCC complaints record the caller ID number, not the caller's actual location, and caller ID can be spoofed). high is set for every country that has a scam profile page, and only for those; low does not mean a number is safe. Evidence about the number itself is in risk.complaints, risk.fcc_complaints, and risk.signals; do not block numbers on scam_risk alone. unknown means we have no rating for the number's country or territory. This covers non-geographic numbers (satellite ranges) and numbers in territories with a null country.name. unknown is also returned for a valid: false result whose prefix is in a known risk range (for example satellite or premium-rate prefixes, listed in risk.signals); on any other valid: false result risk is null. |
risk.scam_types | array of strings | Scam patterns reported for this country (e.g. wangiri, romance). Empty array if none documented. |
risk.advice_url | string | null | Link to the full scam profile page for this country, when one exists. |
risk.complaints | object | null | FTC Do Not Call complaint history for this exact number. This is complaint history, not registration status: DialCode does not check whether a number is on the National Do Not Call Registry. Present only for US numbers with at least one reported complaint; null for non-US numbers or numbers with no reports. Fields: total (int), robocalls (int, subset of total), first_reported_on / last_reported_on (date), categories (array of {code, count}, sorted by count - what consumers reported the calls were about; codes: imposter, debt_reduction, medical, dropped_call, warranties, tech_support, lottery, timeshares, energy, home_improvement, home_security, work_from_home, charity, unspecified, other; category tracking starts 2026-07-19, so counts can lag total for numbers first reported earlier), geography (object | null - victim spread across US states: states (int, distinct states that reported this number - a broad spread means a nationwide robocall campaign, a single state a targeted local one) and top (up to 5 {state, count} sorted by report count); null until state tracking has data for the number, tracked since 2026-07-19), source (string). |
risk.fcc_complaints | object | null | FCC consumer complaint history (unwanted-calls dataset) for this exact number - a second, independent US government source alongside the FTC complaint data. A number present in both is strongly corroborated. Present only for US numbers with at least one FCC complaint. Fields: total (int), first_reported_on / last_reported_on (date), source (string). Tracked since 2026-07-19; the fcc_reported signal fires at 3+ complaints. |
risk.signals | array of objects | Risk signals detected for this specific number: {code, note} pairs from line type, numbering plan, known prefix ranges, and FTC and FCC complaint history. Empty array if none detected. See signal codes below. |
Complaint data comes from the FTC's public Do Not Call complaint files, ingested each weekday as the FTC publishes them (the FTC does not publish weekend files). US numbers only: these are complaints US consumers filed with the FTC.
Signal codes
risk.signals entries come from four layers: line type (detected per number), numbering plan, known prefix ranges (detected from the dial code) and complaints (FTC and FCC complaint counts for US numbers). A number can carry signals from several layers at once.
| Code | Layer | Meaning |
|---|---|---|
voip_line | line type | VoIP number: cheap to obtain anonymously, common in fraud and SMS-verification bypass. For US/Canadian numbers it fires when the range belongs to a VoIP carrier (carrier_details.type is voip, e.g. Bandwidth, Onvoy, Telnyx). |
premium_rate_line | line type | Premium-rate number: calling it incurs elevated charges. |
shared_cost_line | line type | Shared-cost number: partial elevated charges apply. |
fictional_number | numbering plan | US/Canadian number in 555-0100 to 555-0199, which NANPA reserves for films, examples and test forms and never assigns. The number stays valid: true (it is well-formed); filter these rows out of a contact list. |
satellite_range | prefix | Satellite range (+870, +881): very high callback charges, classic wangiri bait. |
international_network_range | prefix | International network range (+882, +883): ITU non-geographic codes outside normal country dialing plans. |
premium_redirect_range | prefix | UK personal numbering range (+4470): missed-call redirect and premium forwarding. |
premium_rate_range | prefix | US 900 premium-rate range (+1900): calls billed at elevated per-minute rates. |
ftc_reported | complaints | US number with 3 or more FTC Do Not Call complaints. |
fcc_reported | complaints | US number with 3 or more FCC consumer complaints (unwanted-calls dataset). |
Batch: POST /v1/phones
Check up to 10,000 numbers in one request. Send Content-Type: application/json and a JSON body with a numbers array (strings or integers). Optionally add country: it applies to every national-format number in the list, while numbers with + keep their own country. Without it, the key's default country applies; an unknown code returns 400 invalid_country. Send the key in the X-Api-Key header, as for single lookups.
$ curl -X POST https://dialcode.app/v1/phones \
-H "X-Api-Key: dc_your_key" -H "Content-Type: application/json" \
-d '{"numbers": ["+639171234567", "(415) 555-0123", "12"], "country": "US"}'
{
"results": [
{ "input": "+639171234567", "valid": true, "e164": "+639171234567", ... },
{ "input": "(415) 555-0123", "valid": true, "e164": "+14155550123", ... },
{ "input": "12", "error": "unparseable_number" }
]
}
resultshas one item per number, in the order sent. Each item is the same objectGET /v1/phone/{number}returns, plusinput: the number as you sent it, always as a string. Match results by position.- Invalid numbers return
valid: false, as in a single lookup. Two cases get an item withinputanderrorinstead: input under 4 digits (error: "unparseable_number") and, on a key with a monthly limit, numbers past that limit (error: "quota_exceeded"). Either way, the rest of the request is answered. - Each number counts as one lookup, unless its item has an
error. A repeated number gets its own item and counts again, so remove duplicates first if you don't need them. - Limit: 5 batch requests per minute per key (see Limits). A request refused with a 4xx status (429 included) is not counted as a lookup. Fix the cause (or wait for
Retry-After), then resend the whole request. Allow an HTTP timeout of at least 30 seconds: a full batch of 10,000 numbers usually takes several seconds and can take longer under load.
Errors
| Status | error | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing or invalid X-Api-Key header. |
| 400 | unparseable_number | Input is too short (under 4 digits) to attempt a lookup. |
| 400 | invalid_country | country is not an ISO 3166-1 alpha-2 code we know, or is sent as a list (country[]=US). Not counted as a lookup. |
| 400 | invalid_numbers | Batch only: numbers is missing, empty, or not an array of strings or integers - usually because the body was not sent as JSON. Not counted as a lookup. |
| 400 | bad_request | The request cannot be read: invalid URL encoding (such as a stray %ff) or the same parameter sent both as a value and as a list (country=US&country[]=GB). Fix the request - retrying it as is fails again. Not counted as a lookup. Other malformed requests get the same code with their own 4xx status. |
| 404 | not_found | No such endpoint - check the path. An empty number (/v1/phone/) also lands here. Returned before the key is checked; not counted as a lookup. |
| 413 | too_many_numbers | Batch only: more than 10,000 numbers. Split the list into several requests. Not counted as a lookup. |
| 429 | quota_exceeded | Monthly limit used up - only for a key that has one. Early-access keys have no monthly limit. In a batch, numbers past the limit get this code per item and the response is still 200. |
| 429 | rate_limited | Per-minute rate limit exceeded (batch: 5 requests / minute). |
| 500 | internal_error | Something broke on our side - retry later with backoff. |
All errors return JSON with a machine code and a human message: {"error": "rate_limited", "message": "Too many requests - slow down and retry after the Retry-After header."}. Both 429 variants ship a Retry-After header (seconds).
Limits & rate-limit headers
- Early access, free: no monthly limit. Lookups are counted per key and calendar month - see
/v1/account/usagebelow. - Rate limit: 300 requests / minute per key (5 a second). On
429 rate_limitedwait forRetry-After; for a big list, use the batch endpoint or upload a CSV in your account. - Batch: 5 requests / minute per key, up to 10,000 numbers each, so up to 50,000 numbers a minute. A batch request also counts toward the 300 requests / minute limit.
- A key with a monthly limit gets
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(unix epoch of the next monthly reset) on every response. Early-access keys have no limit, so the headers are not sent.
GET /v1/account/usage
Usage for the calling key. Free - not counted as a lookup, logs nothing. monthly_quota and remaining are null while the key has no monthly limit; used resets on resets_on.
$ curl https://dialcode.app/v1/account/usage -H "X-Api-Key: dc_your_key"
{
"key_prefix": "dc_1a2b3c4d",
"monthly_quota": null,
"used": 250,
"remaining": null,
"resets_on": "2026-08-01"
}
Examples
curl
curl https://dialcode.app/v1/phone/+639171234567 \ -H "X-Api-Key: dc_your_key"
JavaScript (fetch)
const res = await fetch("https://dialcode.app/v1/phone/+639171234567", {
headers: { "X-Api-Key": "dc_your_key" }
});
const data = await res.json();
console.log(data.risk.scam_risk);
Ruby (Net::HTTP)
require "net/http"
require "json"
uri = URI("https://dialcode.app/v1/phone/+639171234567")
req = Net::HTTP::Get.new(uri)
req["X-Api-Key"] = "dc_your_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts data["risk"]["scam_risk"]
Python (requests)
import requests
res = requests.get(
"https://dialcode.app/v1/phone/+639171234567",
headers={"X-Api-Key": "dc_your_key"},
)
print(res.json()["risk"]["scam_risk"])
PHP (curl)
$ch = curl_init("https://dialcode.app/v1/phone/+639171234567");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: dc_your_key"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
echo $data["risk"]["scam_risk"];
Bulk CSV
Validate a whole file at once: upload a CSV (one number per line, or the column headed Phone / Mobile / Cell / Tel - else the column with the numbers; no row limit, files up to 10 MB) in your account. Each distinct number is checked once; the result CSV (validity, country, carrier, scam risk, FTC/FCC complaint totals, signals, line type and, for US and Canadian numbers, state, timezone and strict_state) is usually ready within seconds and kept for 7 days. If no country is set and nearly every row has 10 digits, or 11 digits starting with 1, the file is read as US/Canada (+1) numbers, unless it is a list of Indian or Chinese mobile numbers. The upload list in your account marks files read this way. To read the file against another country, set the country (or a default country on the key).
Checking from code? Use the batch endpoint instead.
Just want to check a short list? The bulk phone number validator checks up to 50 numbers without a key.
Spec & changelog
- OpenAPI 3.0 spec - import into Postman, Insomnia, or generate a client.
- Changelog - what changed and when.