Carrier Lookup API: The Complete Developer Guide
PilotLookup Team
Author
In this article
1. What Is a Carrier Lookup API?
A carrier lookup API is a REST service that accepts a phone number as input and returns structured data about that number's current carrier assignment, line type, and geographic origin. The key word is current — a carrier lookup API doesn't just tell you who originally issued the number. It tells you who holds it today, accounting for number portability.
In the United States, subscribers have been able to keep their phone number when switching carriers since 2003 — a right called local number portability (LNP). This means the original carrier printed on a SIM card or listed in a static database is often wrong. A number originally issued by AT&T may have been ported to T-Mobile, then ported again to a VoIP provider. A carrier lookup API that queries live portability data reflects all of those changes.
This matters for a wide range of applications. A fraud prevention system that flags VoIP numbers needs accurate, current line-type data — not what the number was when it was first issued. An SMS platform routing messages needs to know the current carrier to select the right delivery path. A CRM enrichment job needs current carrier data to segment contacts correctly. In every case, stale carrier data produces worse outcomes than no data at all.
The carrier lookup API is the tool that bridges the gap between a raw phone number string and actionable, current carrier intelligence.
2. How It Works Under the Hood
When you submit a phone number to a carrier lookup API, several things happen in rapid sequence behind the scenes. Understanding this pipeline helps you evaluate providers accurately and set realistic expectations about what the API can and cannot tell you.
Step 1: Number normalization
The submitted number is parsed and normalized to E.164 format — the international standard that represents every phone number as a plus sign followed by the country calling code and the subscriber number, with no spaces or punctuation. For US numbers, this means +1 followed by the ten-digit number. Normalization ensures the lookup query is consistent regardless of how the user typed the number.
Step 2: Format validation
Before hitting the carrier database, the API validates the number against the numbering plan for its country. For US numbers, this means checking the North American Numbering Plan (NANP) rules: the area code and central office code must both start with a digit between 2 and 9, the number must be exactly ten digits, and certain reserved ranges (like 555-0100 through 555-0199) must be excluded. Numbers that fail format validation return immediately with valid: false — no carrier database query is made.
Step 3: NPAC query
For numbers that pass format validation, the API queries the Number Portability Administration Center (NPAC) — the national database of record for US number portability. The NPAC records every carrier transfer for every US phone number. The API provider syncs NPAC data on a scheduled basis (daily, for the best providers) so that the data returned reflects recent ports rather than the original carrier assignment.
Step 4: Line-type classification
Using the current carrier assignment from NPAC and carrier-level metadata about which number ranges are allocated to mobile, landline, or VoIP services, the API classifies the line type. This classification is what most downstream applications care about most — it determines whether a number can receive SMS, whether it represents elevated fraud risk, and how it should be treated in routing logic.
Step 5: Response assembly and return
The assembled data — validity, carrier name, line type, and geographic fields — is serialized to JSON and returned with an HTTP 200. The entire pipeline, from request receipt to response delivery, completes in roughly 100ms on edge-hosted infrastructure.
3. What Data a Carrier Lookup API Returns
A well-designed carrier lookup API returns a consistent JSON structure on every successful lookup. Here is the complete response from PilotLookup, annotated:
{
"phone": "+12032145454",
"valid": true,
"carrier": "T-Mobile",
"line_type": "mobile",
"city": "Bridgeport",
"state": "CT"
}Field Type What it tells you phone string The normalized E.164 representation of the submitted number. Use this for storage rather than the raw input — it's the canonical, unambiguous form. valid boolean true if the number is assigned to an active subscriber at a recognized carrier. false if unassigned, disconnected, or not a valid US number. This is your primary gate for accept or reject decisions. carrier string The name of the carrier currently holding the number, post-porting. Examples: AT&T, Verizon, T-Mobile, Google Voice, Twilio. Use this for carrier-specific routing and as a secondary fraud signal. line_type string The type of line: mobile, landline, voip, toll-free, or unknown. This is your highest-value field for fraud prevention and SMS routing decisions. city string City associated with the NPA-NXX assignment — the original geographic assignment of the number range. Not the subscriber's current location; ported numbers may show a city that no longer matches the subscriber. state string Two-letter US state code from the NPA-NXX assignment. Same geographic caveat as city.
Understanding line_type values
Value SMS capable? Fraud risk What to do mobileYesLowProceed normally landlineNoLowWarn user; offer voice or email alternative voipYesElevatedFlag for review or additional verification toll-freeNoHigh (user error or abuse)Reject or flag at entry unknownUncertainUnclearTreat conservatively; log for review
4. The NPAC: Why US Carrier Data Is Uniquely Reliable
The Number Portability Administration Center is the detail that separates US carrier lookup data from international carrier data in terms of quality and reliability. Understanding what NPAC is and why it matters helps you appreciate why a carrier lookup API for US numbers can be meaningfully more accurate than equivalent services for international numbers.
NPAC was established by the FCC in 1997 in anticipation of local number portability, which launched in 2003. Every US carrier — from the major networks like AT&T, Verizon, and T-Mobile down to smaller regional operators — is legally required to update NPAC within 24 hours of completing a number port. This legal mandate means NPAC is not just the largest database of US number assignments; it's the most accurate one, updated continuously by the carriers themselves.
When a carrier lookup API provider syncs NPAC daily, the carrier data they return is current to within 24–48 hours in the worst case, and typically within hours for same-day ports. This is the foundation of the 99.9% carrier accuracy claims you'll see from quality providers — it's not a marketing number; it's a direct reflection of NPAC data quality.
The practical implication: a US number that has been ported three times in the last two years will return the correct current carrier from a good carrier lookup API. A static database that maps number prefixes to original carriers will return the wrong carrier for that number — and there's no way to know it's wrong without querying NPAC.
💡 Ask your provider directly
When evaluating a carrier lookup API, ask: do you query NPAC for US carrier data, and how frequently do you sync? A provider that answers this question precisely and confidently is pulling from authoritative data. A provider that says "we use multiple sources" without specifics may be relying on static databases.
5. Primary Use Cases
Fraud prevention at signup
VoIP numbers are the dominant fraud vector in US SaaS and e-commerce applications. They can be provisioned programmatically in seconds, used once to receive a verification SMS, and discarded. At scale, a fraudster can create hundreds of accounts using burner VoIP numbers before any manual review catches the pattern. A carrier lookup API that returns line_type: "voip" during the signup flow gives you the signal you need to flag or block the account before it's created — stopping fraud at the cheapest possible point in the funnel.
SMS deliverability optimization
Every SMS sent to a landline is a wasted message. The recipient never sees it; the delivery status typically shows "delivered" to the platform but the message is silently dropped. If your contact database has a 7% landline rate — a common figure for organically collected lists — and you send to 100,000 contacts at $0.01 per SMS, you're spending $70 per campaign on messages that can never deliver. A carrier lookup API that identifies landlines before sending eliminates that waste and improves your deliverability metrics.
CRM data quality
Phone numbers collected over time without validation accumulate errors: disconnected numbers, format inconsistencies, landlines in a mobile-only field, VoIP numbers in records where mobile is expected. A batch carrier lookup job against your existing CRM data enriches every record with current carrier, line type, and validity information, and lets you segment or clean the database before it pollutes downstream systems.
Account verification and OTP flows
Before sending an OTP via SMS for two-factor authentication or account verification, checking the line type ensures you don't send to numbers that can't receive it. Landlines silently fail. Toll-free numbers should never be provided as personal numbers. VoIP numbers represent elevated risk in security-sensitive flows and may warrant a step-up to app-based TOTP instead of SMS. The carrier lookup API check takes ~100ms and prevents a significant class of verification failures.
Risk scoring and compliance
Carrier data enriches risk models. Knowing that a new account used a VoIP number from a carrier known to issue disposable virtual numbers — versus a mobile number on a major carrier that's been assigned for years — is a meaningful signal in a fraud risk score. Many compliance frameworks for KYC (Know Your Customer) also require verification that a submitted phone number is real and current, which a carrier lookup API satisfies.
6. Integration Walkthrough
Integrating a carrier lookup API into your application follows a consistent three-step pattern regardless of your stack: validate format client-side, call the API server-side, act on the response. Here is a complete Node.js example showing all three steps:
Node.js — full carrier lookup integration
const API_KEY = process.env.PILOTLOOKUP_API_KEY;
// Step 1: Format validation (free — no API call)
function normalizeUSPhone(input) {
const digits = input.replace(/\D/g, '');
const local = digits.startsWith('1') && digits.length === 11
? digits.slice(1) : digits;
if (local.length !== 10) return null;
if (/^[01]/.test(local) || /^[01]/.test(local.slice(3))) return null;
return local;
}
// Step 2: Carrier lookup API call
async function carrierLookup(rawPhone) {
const normalized = normalizeUSPhone(rawPhone);
if (!normalized) return { valid: false, error: 'Invalid format' };
const res = await fetch(
`https://www.pilotlookup.net/api/validate?phone=${normalized}`,
{
headers: { 'Authorization': `Bearer ${API_KEY}` },
signal: AbortSignal.timeout(5000),
}
);
if (!res.ok) throw new Error(`API ${res.status}`);
return res.json();
}
// Step 3: Act on the response
async function handleSignup(phone) {
const result = await carrierLookup(phone);
if (!result.valid) {
return { allow: false, reason: 'invalid_number' };
}
if (result.line_type === 'toll-free') {
return { allow: false, reason: 'toll_free_rejected' };
}
if (result.line_type === 'landline') {
return { allow: true, warn: 'no_sms', carrier: result.carrier };
}
if (result.line_type === 'voip') {
return { allow: true, flag: 'voip_review', carrier: result.carrier };
}
// Mobile — proceed with full enrichment stored
return {
allow: true,
phone: result.phone,
carrier: result.carrier,
lineType: result.line_type,
state: result.state,
};
}The same pattern translates directly to Python (using requests) and PHP (using cURL). The critical architecture decisions are consistent across all stacks: always run format validation before the API call to avoid spending credits on garbage input, always set a request timeout, and always store the enriched data — carrier, line type, state, validated_at — not just a pass/fail boolean.
7. What to Look for in a Carrier Lookup API
Not all carrier lookup APIs are built on the same data or infrastructure. Here are the five dimensions that most directly affect the quality of results you'll get:
NPAC-sourced data with daily sync
For US numbers, there is no substitute for NPAC data. Ask any provider you evaluate whether they use NPAC as their authoritative source for US carrier assignments and how frequently they sync. Daily sync is the minimum acceptable cadence for production use. Anything less means ported numbers may return stale carrier data — which is worse than no data for fraud decisions.
Accurate line-type classification
The carrier name alone is not enough. You need line_type broken out as a structured field — not a carrier name you have to pattern-match against a list of known VoIP providers. Line-type classification should correctly distinguish mobile, landline, VoIP, and toll-free numbers without requiring any work on your end. Test any provider you're evaluating with a set of known VoIP numbers (Google Voice, TextNow, Twilio numbers) and verify the classification is correct.
Response latency under 200ms
For synchronous use in signup or checkout flows, response latency needs to be invisible to users. A carrier lookup API that responds in 100–150ms median adds no perceptible friction. One that responds in 600–800ms is a UX problem. Test latency from your own infrastructure, not from the provider's documented benchmarks, which are measured from ideal conditions that may not match your deployment region.
No data retention
Phone numbers are personal data. Any provider that logs the numbers you submit to their API is creating a data retention liability in your chain. For GDPR, CCPA, and healthcare contexts, this is non-negotiable. Verify the provider's data retention policy in their privacy documentation — not their marketing copy — and confirm they do not store or use submitted phone numbers for any secondary purpose.
Credit-based pricing with no expiry pressure
Pay-as-you-go credit pricing aligns the provider's incentives with yours — they earn when you look up numbers, not when you pay a monthly fee you may or may not fully use. Check whether credits expire, what the per-lookup cost is at your volume tier, and whether there are any minimum purchase requirements that don't match your initial need.
8. Common Questions Answered
Can a carrier lookup API tell me if a number is currently active?
Yes. The valid field returns false for numbers that are unassigned, disconnected, or not recognized in the NPAC database. A true value means the number is currently assigned to an active subscriber at a carrier.
Does it work for numbers that have been ported multiple times?
Yes, for US numbers — because NPAC records every port, not just the most recent one. A number ported three times will return the current carrier regardless of its history. For international numbers, the answer depends on whether the country has a centralized portability database equivalent to NPAC, which many do not.
How is this different from a simple reverse phone lookup?
A reverse phone lookup attempts to identify the person or business associated with a phone number — often pulling from public records or user-contributed databases. A carrier lookup API returns carrier, line type, and geographic data about the number itself, not about the subscriber. It does not return names, addresses, or any personally identifiable information about who owns the number.
Is it safe to call from a browser?
No. Always call the carrier lookup API from your server, never from client-side JavaScript. Exposing your API key in a browser request would allow anyone to extract the key from the source and consume your credits. The API call should be a server-side operation triggered by a form submission or webhook.
What happens if I submit a number that's outside the US?
PilotLookup is purpose-built for US phone validation. Submitting a non-US number will return valid: false — the number won't match any NPAC record. For international number validation, use a separate international lookup service alongside a US-specialist API for your US traffic.
Try the PilotLookup Carrier Lookup API
NPAC-backed US carrier data. ~100ms response. Zero data retention. 10 free lookups to start.
API Docs · support@pilotlookup.net · 1-888-370-6801