Δ

API Changelog

2026-11-20 - Batch lookups: POST /v1/phones, OpenAPI spec 1.11

  • New endpoint POST /v1/phones checks up to 10,000 numbers in one request. The JSON body is {"numbers": [...], "country": "US"}, where country is optional. The response has a results array with one item per number, in the order sent. Each item is the same object GET /v1/phone/{number} returns, plus input. Input under 4 digits, and numbers past a key's monthly limit, get their own error item instead of failing the request. See the API docs.
  • Batch requests are limited to 5 per minute per key, up to 50,000 numbers a minute, and count toward the 300 requests / minute limit. The single-number endpoint is unchanged.
  • OpenAPI spec 1.11 describes the new endpoint.

2026-11-13 - No row limit on list uploads, your columns in the result file

  • CSV uploads in your account have no row limit. The one cap is the file size: 10 MB (was 10,000 rows / 1 MB per file). A phone-only file fits over 600,000 numbers.
  • A file with a header row that names the phone column now comes back as itself. In your account, All rows and the filtered downloads (valid, mobile, landline and the rest) keep your columns as uploaded and add the result columns at the end; on the free bulk validator, the full result file does the same. The input column is left out, since your phone column is already there, and a result column whose name your file already uses is renamed dialcode_ + name, for example dialcode_carrier. Mobile for SMS import is unchanged. Files without a header row get the result columns alone, as before.

2026-11-11 - JSON instead of HTML for more /v1 errors, OpenAPI spec 1.10

  • Requests that used to get an HTML error page now get the usual JSON error: 400 bad_request for invalid URL encoding or a parameter sent both as a value and as a list, 404 not_found for an unknown path, 500 internal_error when something breaks on our side.
  • country sent as a list (country[]=US) returns 400 invalid_country instead of a 500 error.
  • OpenAPI spec 1.10 lists the 500 response on both endpoints and the 400 response on /v1/account/usage.
  • Successful responses are unchanged. If you treated a non-JSON body as a separate failure case, you can now branch on error for these responses too. Gateway errors (502, 504) while the service is down can still come as plain HTML.

2026-11-09 - FTC complaint wording in source and the ftc_reported note

  • risk.complaints.source is now FTC Do Not Call complaints (was FTC Do Not Call registry), and the note of the ftc_reported signal reads, for example, Reported in 47 FTC Do Not Call complaints (30 robocall reports) (was Reported to the FTC Do Not Call registry 47 times (30 robocall reports)). The data consists of consumer complaints from the FTC's public complaint files; DialCode does not check numbers against the National Do Not Call Registry.
  • The signal codes table in the API docs now lists fcc_reported, which the API has returned since 2026-07-19.
  • Codes, fields and counts are the same. If you matched the old source string, check instead that risk.complaints is not null. source and note are text for people: branch on code, not on the wording.

2026-11-09 - State and time zone in bulk CSV results

  • Three new columns at the end of the bulk CSV (dashboard upload and keyless bulk validator): state (US state or territory, or Canadian province, from the NANPA/CNAC range), timezone (IANA time zone where the number was issued; two zones joined with | when the area is split by a time zone boundary and we cannot tell which side the number is on) and strict_state (true for the states we track whose telemarketing law covers texts and is stricter than federal rules). Empty for numbers outside the US and Canada and for +1 numbers without range data; strict_state is true or false. No breaking change: existing columns keep their names and positions.
  • The result page (not the CSV) shows, per time zone, which numbers you can contact now (federal hours 8 am-9 pm local, stricter state hours where we track them, CRTC call hours for Canada) and how long until the window opens or closes. For planning a send, not legal advice.
  • The single-number API response is unchanged: carrier_details.region and carrier_details.rate_center already carry the state and rate center.

2026-11-04 - Broken rows in +1 bulk files, clearer hints for invalid numbers

  • Behavior change: in a bulk check with no country set, when the file is read as US/Canada (+1) numbers (nearly every row has 10 digits, or 11 starting with 1), a row that does not fit +1, such as a number cut to 9 digits, now comes back not_a_number with a hint saying what is wrong with it. It used to come back needs_country with a list of other countries to try. If you count needs_country rows or re-check them with another country, expect fewer of them.
  • When a lookup names a country (?country=, the API key's default country, or the country field of a CSV upload) and the number is invalid under it, hint now says what is wrong under that country instead of asking you to pass one, for example Not a valid US/Canada (+1) number: 9 digits, expected 10. If it is from another country, send it in E.164 form (+ and country code). A valid number from another +1 country gets This is a valid CA number, not US: pass country=CA or send it as +16132345678.
  • An invalid +1 number sent without a country also gets a hint saying what is wrong, for example Not a valid US/Canada (+1) number: 9 digits, expected 10.
  • reason and candidates of these lookups are unchanged. hint is text for people: branch on reason, not on the hint wording.

2026-11-04 - No monthly limit, OpenAPI spec 1.9

  • During early access, API keys have no monthly limit (it was 10,000 lookups a month). Existing keys are included. The per-minute rate limit (300 requests per key) and the CSV size limit (10,000 rows / 1 MB per file) still apply.
  • GET /v1/account/usage returns monthly_quota: null and remaining: null for a key without a limit; used still counts this month's lookups.
  • The X-RateLimit-* headers are sent only for a key that has a monthly limit, so early-access keys no longer get them. quota_exceeded is returned only for a key with a monthly limit.
  • If your client reads monthly_quota, remaining or the X-RateLimit-* headers, handle null and a missing header.

2026-11-03 - fictional_number signal

  • New risk signal fictional_number for US/Canadian numbers in 555-0100 to 555-0199. NANPA reserves this range for fiction and examples, so such a number is never a real subscriber. valid does not change. In bulk CSV results the code shows up in the signals column.

2026-11-03 - OpenAPI spec 1.8

  • The OpenAPI spec now matches the responses field for field: line_type lists every value it currently takes, country.name is marked nullable (it is null for territories such as Guam), carrier_details.type lists null among its values, and fields present in every response are marked required. Responses did not change. If you generate a client from the spec, regenerate it, then handle a null country.name and treat a line_type you do not know as fixed_or_mobile.

2026-10-31 - line type for US/Canada numbers

  • Behavior change: line_type of a geographic US/Canada number is now mobile, fixed_line, voip or pager, based on the network type of the carrier that holds its range (the same data as carrier_details.type). It used to be fixed_or_mobile, and still is when we cannot classify the range holder. Toll-free and premium-rate numbers keep toll_free / premium_rate. Ported numbers are not detected.
  • Bulk CSV duplicates: a number that appears earlier in the file comes back with error = duplicate and uses no lookup. Uploading the same file with the same country again within 7 days returns the existing result instead of a new check.
  • Bulk CSV column order changed (dashboard upload and keyless bulk validator): input, valid, line_type, carrier, e164, country_code, country_name, error, reason, hint, scam_risk, ftc_complaints, fcc_complaints, signals. The carrier_type column is gone - line_type now holds this value. Read columns by header name, not position.

2026-10-30 - bulk CSV reads US/Canada numbers without +1

  • Behavior change: a bulk check (dashboard CSV upload, or a pasted list or CSV in the keyless bulk validator) with no country set, in which nearly every row has 10 digits, or 11 digits starting with 1, is now read as US/Canada (+1) numbers, unless it is a list of Indian or Chinese mobile numbers. 10-digit rows used to come back valid: false with needs_country. Rows with a + code are read as written. Setting a country on the upload, or a default country on the API key, turns this off. Single lookups by API are unchanged.
  • When many rows still come back with needs_country, the dashboard (next to the upload) and the bulk validator (above the result) say so, in addition to the hint column.

2026-10-30 - early access

  • The API is free during early access, and the monthly quota is now 10,000 lookups per key (was 1,000) - existing keys included. X-RateLimit-Limit and /v1/account/usage show the new limit.

2026-10-21 - v1.7

  • Behavior change: carrier is now filled for US and Canadian numbers - from the NANPA thousands-block and central office code records and the CNAC code records, reloaded weekly. It used to be null for every +1 number. Same caveat as elsewhere: the carrier the range was assigned to, not the current one after porting.
  • carrier_details - legal entity, OCN, network type (mobile / landline / voip / paging), rate center, region, assignment date and source. type tells mobile from landline for NANP numbers, where line_type stays fixed_or_mobile.
  • Behavior change: the voip_line signal now also fires for US/Canadian numbers in ranges held by VoIP carriers (Bandwidth, Onvoy, Telnyx, ...).
  • CSV results carry a carrier_type column (last column).

2026-10-18 - v1.6

  • Behavior change: numbers from regions we have no country profile for (Guam, US Virgin Islands, Jersey, Guernsey, Isle of Man, Reunion and a few more) now come back valid: true with e164, formats and line type. They used to be reported as valid: false even though they are real numbers. country.name is null for them and risk.scam_risk is unknown.
  • Behavior change: satellite and other non-geographic numbers (+881, +870, +883, +800) are now valid: true with their e164; country stays null, and the range signals (satellite_range, international_network_range) are unchanged.

2026-09-07 - v1.5

  • reason on every valid: false result - needs_country (a real national number, country missing) or not_a_number (no numbering plan accepts it). Half of one integration's rejections were the former, and nothing in the response said so.
  • candidates - the countries a bare national number would resolve under, so needs_country is actionable without guessing.
  • Default country per key, set in the dashboard: lookups and CSV uploads that pass no country are read against it. ?country= still overrides.
  • CSV results carry a reason column.

2026-08-17 - v1.4

  • ?country=XX - read a national-format number (8663982896, 866-398-2896) against that country's numbering plan. Same option for CSV uploads, where it applies to the whole file.
  • hint field on every valid: false result - says what would resolve the number instead of leaving you with an empty payload.
  • New error 400 invalid_country for an unknown country code. Spends no quota.
  • Per-key rate limit raised from 60 to 300 requests / minute - a script walking a list no longer trips it.

2026-07-19 - v1.3

  • formats.national / formats.international - display-ready number formats.
  • country.timezone - IANA capital timezone for all 205 countries.
  • carrier - range-holder carrier (allocation-time, null for US/CA and most landlines).
  • risk.complaints.categories - what FTC complainants said the calls were about (15 category codes).
  • risk.complaints.geography - victim spread across US states (distinct count + top 5).
  • risk.fcc_complaints + fcc_reported signal - independent second US government source (FCC unwanted-calls complaints).
  • New endpoint GET /v1/account/usage - quota state, free.
  • Error responses carry a human message; every keyed response ships X-RateLimit-* headers; all 429s ship Retry-After.
  • Quota alert emails at 75% / 90% / 100%. OpenAPI spec published at /openapi.yaml.

2026-07-19 - v1.2

  • risk.complaints - FTC Do Not Call complaint history per US number (220K+ numbers, ingested daily).

2026-07-18 - v1.1

  • risk.signals - per-number risk signals: line type (VoIP / premium / shared-cost) and known-bad prefix ranges (satellite, premium, UK 070).

2026-07-18 - v1.0

  • Launch: GET /v1/phone/{number} - validation, E.164, country, line type, area, country scam profile. Free 1,000 lookups/month, magic-link cabinet.