Know what a number is before you dial it.
One POST request turns any phone number into its E.164 form, line type, carrier and region, checks the regulator’s own allocation table for the block it sits in, and flags fictional, virtual and disposable numbers, answered in milliseconds from local data with a typed reason for every invalid number.
Free credits every month. No credit card required. The demo on this page runs against the live service.
Live demo
POST /demo/phone · no key needed
Response
Look up any number to see the full API response, straight from the live service. National formats need the country.
Every response field, documented.
This is the actual contract of POST /api/v1/phone — signals are tri-state: false is a checked negative, null means the dataset was not consulted. Each response also carries sources naming the datasets actually used with their versions, and meta with your credit usage.
| Field | Type | What it tells you |
|---|---|---|
| valid | Whether the number is assignable: valid for its numbering plan and, where the regulator’s table is installed, inside an allocated block. A number in a range reserved for fiction (is_fictional) answers valid even where the regulator lists its block as protected. | |
| reason | Why it is not valid: missing_country, invalid_country_code, too_short, too_long, not_a_number, invalid_length, invalid_number, unassigned_block, emergency_number or short_number. unassigned_block still carries the parsed number and its block status; every other reason answers null fields. | |
| e164 | The canonical +14155550142 form to store and dedupe by. | |
| national / international / rfc3966 | Display formats, (415) 555-0142 and +1 415-555-0142, and the tel: URI for click-to-call links. | |
| country / country_name / calling_code | ISO 3166-1 alpha-2 code, its English name and the country calling code. Country is null for non-geographic numbers such as international toll-free (+800). | |
| continent / is_eu / currency | The country’s continent code, EU membership and ISO 4217 currency, the same facts the IP lookup answers, so one code path can set defaults from either. | |
| line_type / line_type_source | mobile, fixed_line, fixed_line_or_mobile, voip, toll_free, premium_rate, shared_cost, personal_number, pager, uan, voicemail or unknown; a UK 084 or 087 number is shared_cost, as Ofcom’s plan classes it. The source is numbering_plan when the metadata decides, block_allocation when a North American fixed_line_or_mobile number was settled by its block holder: a wireless carrier’s block is mobile, a virtual-number wholesaler’s is voip. | |
| carrier / carrier_source | The block holder as the regulator lists it (block_allocation), or the carrier the metadata knows for the prefix (numbering_plan). Both reflect the original allocation, never a later port. | |
| block_status | What the regulator’s table says about the block the number sits in: allocated to a holder, unassigned (free, protected or quarantined, so no number in it can be in service) or reserved for special use. Null when no table covers the region. | |
| region | Human-readable geographic description, e.g. "San Francisco, CA". | |
| is_geographic | Whether the number is tied to a place (fixed lines and geographic mobiles) rather than a service such as toll-free. | |
| timezones | All IANA time zones the number can belong to: one for most numbers, several for country-wide ranges, empty for non-geographic numbers. | |
| extension | The parsed extension ("123" from input like "ext 123"), kept out of the E.164 form. | |
| is_fictional | The number sits in a range reserved for fiction and drama: the NANP 555-01XX block and the drama ranges and numbers of Ofcom, ARCEP, ACMA and ComReg. Still valid, never in service. | |
| is_virtual | The block is held by a virtual-number wholesaler or VoIP provider, the numbers behind apps, softphones and SMS-receiving services. Null when no regulator table covers the number. | |
| is_disposable | The number is published by an SMS-receiving website, so anyone can read a code sent to it. Null until the list is installed. | |
| disposable_seen_at | When the SMS-receiving list last saw the number, where the list says so. A listing weighs less once it is more than a year old, or 90 days old if every list has dropped the number, because the number may have been reassigned since. | |
| risk_score | A transparent sum you can recompute: fictional +80, disposable +70 (+40 once the listing is over a year old, or over 90 days old after every list dropped the number), your own abuse report +60, your own failed delivery +50, abuse reports from three or more accounts +40, premium rate +60 (in the UK, 09 numbers), reserved block +40, virtual +40, a burst of lookups in one 1,000-number range +40, VoIP +30, pager +30, digit pattern +30, many numbers from one client IP +30, a range dense with SMS-receiving numbers +30, international network +30, shared cost +20 (including UK 084 and 087), unwanted-call complaints +20, capped at 100. Null for invalid numbers. | |
| risk_level | low under 30, medium from 30, high from 60. | |
| risk_signals | Each contributing signal with the weight applied and the dataset behind it, so the weights always sum to risk_score. | |
| hlr_checked / reachable / ported / current_carrier / roaming | What the live carrier-network check found, run only when a lookup asks for it with hlr: true; without it reachable, ported, current_carrier and roaming answer null. The live carrier-network check (hlr: true) is not enabled on the service: hlr_checked answers false and nothing extra is charged. | |
| carrier_code / carrier_brand | The regulator’s own code for the block holder, and the network brand behind its legal name ("AT&T" for NEW CINGULAR WIRELESS PCS) from a bundled, versioned map. Both describe the original allocation. | |
| block_pooled / block_assigned_at | Whether a North American code is pooled into thousands-blocks (in the United States, carrier and line_type then come from the number’s own block where NANPA lists it), and when the regulator assigned the code or range (for a pooled US code, the number’s own block, where NANPA dates it; never the code’s date, which says nothing about the number’s block). | |
| region_level | How specific region is: locality (a rate centre or a place with its state), area (the area a code covers) or country (only the country’s name, as for most mobiles). | |
| local_time / utc_offsets / in_call_window | The local time at the number when its zones agree, the current UTC offsets across them, and, when you send call_window, whether now is inside it everywhere the number can be. | |
| did_you_mean | For an invalid number, the one valid reading of what was typed, such as a missing + or a foreign international prefix left in. | |
| range_seen_by_you / client_velocity / destination_new_for_you | Your own traffic: distinct numbers your account looked up in the same 1,000-number range, distinct numbers tried from one client IP, and whether the country is new for your account. Counts only, never another account’s, and never on publishable-key answers. | |
| complaints_90d / complaints_last_at | North American numbers only: consumer complaints naming the number as the caller in the FTC’s reported-calls data over the last 90 days, and the latest date. | |
| ok_to_send / blocked_by | Your SMS policy’s decision and, when it says no, why: invalid, suppressed, opted_out, country, line_type, a risk signal, risk_score, unreachable or unconfirmed. Set the countries, line types and signals you refuse once, on the account. A fraud and deliverability decision, not consent and not a do-not-call scrub. |
One request, built for the numbers people actually type.
- International format works with no extra parameters
- National format resolves with a two-letter country
- Emergency numbers and short codes are named, not called too short
- Invalid numbers return a typed reason, free of charge
- Batches of 1,000 per call, bulk runs of 100,000 with a CSV and a signed webhook
- Repeats of a charged lookup are free for seven days
$ curl https://spaw.co/api/v1/phone \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"phone": "+1 205 208 0142"}' { "success": true, "data": { "valid": true, "e164": "+12052080142", "national": "(205) 208-0142", "country": "US", "line_type": "voip", "line_type_source": "block_allocation", "carrier": "BANDWIDTH.COM CLEC, LLC - AL", "block_status": "allocated", "region": "Alabama", "timezones": ["America/Chicago"], "is_fictional": false, "is_virtual": true, "is_disposable": false, "disposable_seen_at": null, "risk_score": 40, "risk_level": "medium", "risk_signals": [{ "signal": "virtual", "weight": 40, … }], "hlr_checked": false, "ok_to_send": true, "blocked_by": null, "sources": [{ "dataset": "nanpa-co-codes", … }, …], … }, "meta": { "credits_used": 1, "credits_remaining": 499, "cache_hit": false } }
Every data source, named in every response.
The sources block lists exactly the datasets a lookup consulted, with the version of each, so you can audit any answer against the public tables it came from. Every numbering region’s calling code and number formats, and the regulator table that covers it where there is one, are under phone facts by country. Who publishes each table, the files, the terms as the publisher states them and what the copy installed here holds are under phone data sources, one page per publisher.
| Dataset | Covers | Refreshed | Terms |
|---|---|---|---|
| libphonenumber | Numbering-plan metadata for 240+ regions: validity, formats, line types, carrier prefixes, time zones. | ||
| nanpa-co-codes | NANPA’s central office code report and thousands-block report: which US codes and blocks of a thousand (states and territories) are assigned, and to whom. | ||
| cnac-co-codes | The Canadian Numbering Administrator’s code status table, block by block. | ||
| ofcom-numbering | Ofcom’s National Numbering Scheme for the UK and the Crown dependencies: allocated, protected and free blocks. | ||
| arcep-numbering | ARCEP’s numbering resources for France and its overseas regions: attributed ranges and frozen ones, with the operator behind each. | ||
| acma-numbering | The ACMA numbering register for Australia: allocated and spare ten-digit ranges with their current holder. | ||
| acm-nummerregister | ACM’s number register for the Netherlands: assigned, cooling-off and blocked ranges with their holder. | ||
| nad-number-register | The Number Administration Deed register for New Zealand: assigned, spare and reserved codes with their holder. | ||
| ift-numeracion | Mexico’s national numbering plan, published by the CRT (formerly the IFT): every assigned range with its operator and modality. | ||
| uke-numeracja | UKE’s numbering tables for Poland: fixed and mobile scopes with the operator behind each, and the space UKE holds in reserve. | ||
| mimit-numerazione | MIMIT’s workbook of assigned numbering for Italy: mobile, nomadic and geographic ranges with the operator each was assigned to. | ||
| disposable-phone-numbers | Numbers published by SMS-receiving websites, from two open community lists; a number that leaves them is kept at its last-seen date for two years. | ||
| us-complaint-reports | Complaints consumers filed with the FTC naming a North American number as the caller: counts and dates over 90 days, never the consumer. Unverified and often spoofed, so context rather than proof. | ||
| fictional-ranges | The NANP 555-01XX block and the drama ranges and numbers of Ofcom, ARCEP, ACMA and ComReg. | ||
| carrier-brands | The network brand behind a carrier’s legal name (carrier_brand), from the main operators’ entities, former names and operating company numbers. |
Data synced on 2026-10-16: the newest regulator table, listed-number list and rate-centre map behind the answers on this page. Every response carries the same dates in its sources block.
What the regulators’ tables actually settle, measured weekly.
Every week we count, table by table, how many blocks are allocated, how many of those name a holder, and how many settle a line type. For the North American tables that last share is exactly how often a fixed_line_or_mobile number gets resolved. These are shares of the regulators’ tables, not of real traffic: a busy block and an empty one count the same. Last measured 2026-10-11 with libphonenumber 9.0.40.
| Dataset | Countries | Blocks | Allocated | Holder named | Line type settled | Mobile agreement | Version |
|---|---|---|---|---|---|---|---|
| nanpa-co-codes | US PR VI GU AS MP | 205,119 | 96.8% | 100.0% | 44.8% | ||
| cnac-co-codes | CA | 46,400 | 62.0% | 100.0% | 45.4% | ||
| ofcom-numbering | GB | 343,860 | 36.2% | 100.0% | 3.3% | ||
| arcep-numbering | FR GP BL MF MQ GF RE YT PM | 22,637 | 93.2% | 100.0% | 9.4% | ||
| acma-numbering | AU | 99,615 | 91.1% | 100.0% | 26.9% | ||
| acm-nummerregister | NL | 84,430 | 97.7% | 100.0% | 7.5% | ||
| nad-number-register | NZ | 9,718 | 52.5% | 99.9% | 13.5% | ||
| ift-numeracion | MX | 640,255 | 100.0% | 100.0% | 36.9% | ||
| uke-numeracja | PL | 47,175 | 51.5% | 100.0% | 4.2% | ||
| mimit-numerazione | IT | 59,587 | 100.0% | 100.0% | 0.8% |
The disposable-number list holds 129,884 numbers; 84.3% were last seen more than 365 days ago and weigh less in the risk score, because the number may have been reassigned since; so does a number every list has dropped, 90 days after it was last seen.
Where one credit pays for itself.
Stop junk signups
Reject fictional, disposable and premium-rate numbers at registration, flag virtual-number blocks that back OTP farms, and catch typos before you pay to send a code that can never arrive.
Dial at the right moment
Normalize to E.164 for your telephony stack, route by line type, and use the time zone to call when people are actually awake.
Clean your CRM once
Bulk-normalize legacy formats into one canonical form, mark every repeat with the row it repeats and download the list deduped, and drop records that were never real numbers, including blocks the regulator has not allocated.
What we won’t pretend to know.
Numbering plans and allocation tables answer a lot, and have hard limits. We document them instead of papering over them with invented confidence.
Block data is not port-aware
carrier and block_status come from the regulators’ allocation tables: who the block was handed to, not who serves the number today. A ported number keeps its original holder here, because only a live query into the carrier networks can see a port, and we do not guess. The live carrier-network check (hlr: true) is not enabled on the service: hlr_checked answers false and nothing extra is charged.
US line types come from the block holder, or not at all
The North American plan assigns mobiles and landlines from the same blocks. When the block holder is a wireless carrier or a virtual-number wholesaler we say mobile or voip and mark line_type_source block_allocation; otherwise the honest answer stays fixed_line_or_mobile. Most US codes are pooled into thousands-blocks other carriers can hold; NANPA publishes who holds each block, so there the holder is the number’s own block holder, and block_pooled says the code is pooled.
Valid does not mean in service
We verify a number is assignable, formatted, classified and inside an allocated block, not that a handset is switched on. A number in a range reserved for fiction (is_fictional) answers valid even where the regulator lists its block as protected, and is never in service. Only a live carrier-network check can say a handset is reachable, and its answer is never simulated.
Common questions about phone lookups.
Can you tell me whether a number is active right now?
No, and we will not pretend to. Live status needs an HLR or number-portability query into the carrier networks, which costs real money per lookup. The live carrier-network check (hlr: true) is not enabled on the service: hlr_checked answers false and nothing extra is charged. The request flag and the response fields (hlr_checked, reachable, ported, current_carrier, roaming) are already part of the contract, so a client written against them needs no change.
Are there test numbers for my integration tests?
Eight, in the Washington 555-01XX fiction block: +1 202 555 0100 (mobile), 0101 (landline), 0102 (virtual number), 0103 (disposable), 0104 (unassigned block), 0105 (fictional), 0106 (invalid) and 0113 (in a range crowded with SMS-receiving numbers). Each answers the same fixed result every time, costs nothing and leaves no repeat marker, so a test suite never spends credits or depends on the day’s data.
What does unassigned_block mean?
The numbering plan allows the number, but the regulator’s own table says nobody holds the block it sits in: no carrier was ever assigned that code, or the block is free, protected or quarantined. No handset can be reached there, so the number answers valid false, and it costs nothing. The inference only runs from a table synced within the last 45 days.
Why did my US number come back as fixed_line_or_mobile?
Because the North American Numbering Plan assigns mobiles and landlines from the same blocks. We only say mobile or voip when the block holder settles it (a wireless carrier, a virtual-number wholesaler), and line_type_source tells you that is what happened. Any API that claims certainty beyond that is guessing.
What formats can I send?
Anything a human might type. International format ("+1 415 555 0142") works as-is; national format ("(415) 555-0142") needs the two-letter country parameter, which also names that region’s emergency numbers and short codes so 911 answers emergency_number instead of too_short. Extensions like "ext 123" are parsed and returned separately.
Can I use 555 numbers in my tests?
Yes. The 555-01XX block and the drama ranges of Ofcom, ARCEP, ACMA and ComReg are reserved for fiction, so they stay valid (all but Ireland’s 020, which the plan gives no line type), are flagged is_fictional, and carry a risk signal of 80. They behave like any other valid number, including the 1-credit charge. To exercise each answer in a test suite for free, use the documented test numbers (+1 202 555 0100 to 0106 and 0113) instead.
What is the disposable list?
An open list of numbers that SMS-receiving websites publish so anyone can read the codes sent to them. A number on it is real and in service, which is exactly the problem: an OTP sent there proves nothing. The flag answers null until the list is installed, never false by default.
Where does the data come from?
Google’s libphonenumber metadata for the numbering plans, the regulators’ own allocation tables for the United States (NANPA), Canada (CNAC), the United Kingdom (Ofcom), France (ARCEP), Australia (ACMA), the Netherlands (ACM), New Zealand (NAD), Mexico (the CRT, formerly the IFT), Poland (UKE) and Italy (MIMIT), two open lists of SMS-receiving numbers, the complaints about unwanted calls the FTC publishes, and the published fictional ranges. Every response names the datasets it consulted and the version of each, and lookups run on our servers, which is why answers take milliseconds. The one call that would ask a partner, for that one number, is the opt-in live carrier-network check, which is not enabled on the service.
Guides
All guides- An area code is not a time zone
- Fictional and test phone numbers: the ranges regulators reserve and what a lookup answers
- How to store phone numbers in E.164
- Number pooling: why a US code's holder is often not your block's holder
- SMS delivery error codes: retry, remove the number, or fix your sender
- SMS pumping (artificially inflated traffic): what the default SMS policy lets through
- UK number ranges in a phone lookup, from 01 to 09
- What FTC unwanted-call complaints can and cannot say about a number
- Gate SMS verification codes with the SMS policy
- Stop OTP abuse with block data and disposable numbers
- What an unassigned block means
- Why US numbers cannot be split into mobile and landline
Validate your first number in minutes.
Create a key, send one POST request, and keep free lookups every month on us.