Δ
API Changelog
2026-11-20 - Batch lookups: POST /v1/phones, OpenAPI spec 1.11
- New endpoint
POST /v1/phoneschecks up to 10,000 numbers in one request. The JSON body is{"numbers": [...], "country": "US"}, wherecountryis optional. The response has aresultsarray with one item per number, in the order sent. Each item is the same objectGET /v1/phone/{number}returns, plusinput. Input under 4 digits, and numbers past a key's monthly limit, get their ownerroritem 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
inputcolumn is left out, since your phone column is already there, and a result column whose name your file already uses is renameddialcode_+ name, for exampledialcode_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_requestfor invalid URL encoding or a parameter sent both as a value and as a list,404 not_foundfor an unknown path,500 internal_errorwhen something breaks on our side. countrysent as a list (country[]=US) returns400 invalid_countryinstead 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
errorfor 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.sourceis nowFTC Do Not Call complaints(wasFTC Do Not Call registry), and thenoteof theftc_reportedsignal reads, for example,Reported in 47 FTC Do Not Call complaints (30 robocall reports)(wasReported 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
sourcestring, check instead thatrisk.complaintsis notnull.sourceandnoteare text for people: branch oncode, 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) andstrict_state(truefor 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_stateistrueorfalse. 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.regionandcarrier_details.rate_centeralready 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_numberwith a hint saying what is wrong with it. It used to come backneeds_countrywith a list of other countries to try. If you countneeds_countryrows 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,hintnow says what is wrong under that country instead of asking you to pass one, for exampleNot 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 getsThis is a valid CA number, not US: pass country=CA or send it as +16132345678. - An invalid
+1number sent without a country also gets a hint saying what is wrong, for exampleNot a valid US/Canada (+1) number: 9 digits, expected 10. reasonandcandidatesof these lookups are unchanged.hintis text for people: branch onreason, 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/usagereturnsmonthly_quota: nullandremaining: nullfor a key without a limit;usedstill 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_exceededis returned only for a key with a monthly limit. - If your client reads
monthly_quota,remainingor theX-RateLimit-*headers, handlenulland a missing header.
2026-11-03 - fictional_number signal
- New risk signal
fictional_numberfor 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.validdoes not change. In bulk CSV results the code shows up in thesignalscolumn.
2026-11-03 - OpenAPI spec 1.8
- The OpenAPI spec now matches the responses field for field:
line_typelists every value it currently takes,country.nameis marked nullable (it is null for territories such as Guam),carrier_details.typelistsnullamong 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 nullcountry.nameand treat aline_typeyou do not know asfixed_or_mobile.
2026-10-31 - line type for US/Canada numbers
- Behavior change:
line_typeof a geographic US/Canada number is nowmobile,fixed_line,voiporpager, based on the network type of the carrier that holds its range (the same data ascarrier_details.type). It used to befixed_or_mobile, and still is when we cannot classify the range holder. Toll-free and premium-rate numbers keeptoll_free/premium_rate. Ported numbers are not detected. - Bulk CSV duplicates: a number that appears earlier in the file comes back with
error=duplicateand 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. Thecarrier_typecolumn is gone -line_typenow 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: falsewithneeds_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 thehintcolumn.
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-Limitand/v1/account/usageshow the new limit.
2026-10-21 - v1.7
- Behavior change:
carrieris 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 benullfor 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, networktype(mobile/landline/voip/paging), rate center, region, assignment date andsource.typetells mobile from landline for NANP numbers, whereline_typestaysfixed_or_mobile.- Behavior change: the
voip_linesignal now also fires for US/Canadian numbers in ranges held by VoIP carriers (Bandwidth, Onvoy, Telnyx, ...). - CSV results carry a
carrier_typecolumn (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: truewithe164, formats and line type. They used to be reported asvalid: falseeven though they are real numbers.country.nameisnullfor them andrisk.scam_riskisunknown. - Behavior change: satellite and other non-geographic numbers (
+881,+870,+883,+800) are nowvalid: truewith theire164;countrystaysnull, and the range signals (satellite_range,international_network_range) are unchanged.
2026-09-07 - v1.5
reasonon everyvalid: falseresult -needs_country(a real national number, country missing) ornot_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, soneeds_countryis actionable without guessing.- Default country per key, set in the dashboard: lookups and CSV uploads that pass no
countryare read against it.?country=still overrides. - CSV results carry a
reasoncolumn.
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.hintfield on everyvalid: falseresult - says what would resolve the number instead of leaving you with an empty payload.- New error
400 invalid_countryfor 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_reportedsignal - 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 shipsX-RateLimit-*headers; all 429s shipRetry-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.