$

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

FieldTypeDescription
validbooleanWhether the number parses as a real, dialable number. Satellite and other non-geographic numbers (+881, +883, +800) count as valid.
e164string | nullNormalized E.164 form. Null when valid is false.
reasonstringPresent only when valid is false: needs_country (a real national number, country missing) or not_a_number (no numbering plan accepts it).
candidatesarray of stringsPresent 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.
hintstringPresent 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.codestring | nullISO 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_codestring | nullInternational dialing code (e.g. +63).
country.namestring | nullCountry 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.timezonestring | nullIANA 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.nationalstring | nullNumber formatted for domestic dialing (e.g. 0917 123 4567). Null when valid is false.
formats.internationalstring | nullHuman-readable international format with spacing (e.g. +63 917 123 4567). Use e164 for machine comparison.
carrierstring | nullCarrier 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_detailsobject | nullWhere 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_typestring | nullLine 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.codestring | nullLocal area code, when the country has area-code data and one matches.
area.namestring | nullCity / region for the matched area code.
risk.scam_riskstringlow, 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_typesarray of stringsScam patterns reported for this country (e.g. wangiri, romance). Empty array if none documented.
risk.advice_urlstring | nullLink to the full scam profile page for this country, when one exists.
risk.complaintsobject | nullFTC 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_complaintsobject | nullFCC 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.signalsarray of objectsRisk 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.

CodeLayerMeaning
voip_lineline typeVoIP 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_lineline typePremium-rate number: calling it incurs elevated charges.
shared_cost_lineline typeShared-cost number: partial elevated charges apply.
fictional_numbernumbering planUS/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_rangeprefixSatellite range (+870, +881): very high callback charges, classic wangiri bait.
international_network_rangeprefixInternational network range (+882, +883): ITU non-geographic codes outside normal country dialing plans.
premium_redirect_rangeprefixUK personal numbering range (+4470): missed-call redirect and premium forwarding.
premium_rate_rangeprefixUS 900 premium-rate range (+1900): calls billed at elevated per-minute rates.
ftc_reportedcomplaintsUS number with 3 or more FTC Do Not Call complaints.
fcc_reportedcomplaintsUS 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" }
  ]
}
  • results has one item per number, in the order sent. Each item is the same object GET /v1/phone/{number} returns, plus input: 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 with input and error instead: 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

StatuserrorMeaning
401invalid_api_keyMissing or invalid X-Api-Key header.
400unparseable_numberInput is too short (under 4 digits) to attempt a lookup.
400invalid_countrycountry is not an ISO 3166-1 alpha-2 code we know, or is sent as a list (country[]=US). Not counted as a lookup.
400invalid_numbersBatch 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.
400bad_requestThe 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.
404not_foundNo such endpoint - check the path. An empty number (/v1/phone/) also lands here. Returned before the key is checked; not counted as a lookup.
413too_many_numbersBatch only: more than 10,000 numbers. Split the list into several requests. Not counted as a lookup.
429quota_exceededMonthly 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.
429rate_limitedPer-minute rate limit exceeded (batch: 5 requests / minute).
500internal_errorSomething 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/usage below.
  • Rate limit: 300 requests / minute per key (5 a second). On 429 rate_limited wait for Retry-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-Remaining and X-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

Get a free API key →