One endpoint: send a phone number, 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 /api/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}

{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. Numbers without enough digits, or 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 does not spend quota. The same option exists for CSV uploads in the dashboard, 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 the dashboard 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",
  "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

Complaint data comes from the FTC's public Do Not Call registry CSVs, ingested daily (weekday publishing schedule - the FTC does not publish weekend files). US numbers only: the Do Not Call registry is a US program.

Signal codes

risk.signals entries come from two layers: line type (detected per-number) and known prefix ranges (detected from the dial code). A number can carry signals from both layers at once.

Errors

All errors return JSON with a machine code and a human message: {"error": "quota_exceeded", "message": "Monthly quota exhausted. It resets on the 1st (UTC) - see Retry-After."}. Both 429 variants ship a Retry-After header (seconds).

Limits & rate-limit headers

• Free tier: 1,000 requests / calendar month, resets on the 1st.
• Rate limit: 300 requests / minute per key, checked separately from the monthly quota - a script walking a list will not trip it.
• Every keyed response carries monthly-quota telemetry: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch of the next monthly reset).
• Quota alert emails at 75% / 90% / 100% usage - no surprise cutoffs.

GET /v1/account/usage

Quota state for the calling key. Free - consumes no quota, logs nothing.

$ curl https://dialcode.app/v1/account/usage -H "X-Api-Key: dc_your_key"

{
  "key_prefix": "dc_1a2b3c4d",
  "monthly_quota": 1000,
  "used": 250,
  "remaining": 750,
  "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 first column, 10,000 rows / 1 MB max) in the dashboard. Each parsed row spends one quota request; the result CSV (validity, country, carrier, scam risk, FTC/FCC complaint totals, signals) is ready for download within a minute and kept for 7 days.

Spec & changelog

• OpenAPI 3.0 spec - import into Postman, Insomnia, or generate a client.
• Changelog - what changed and when.

Get a free API key →