Telecom & Communications
Phone Number Intelligence API
A phone number looks like a simple field until you try to validate one properly. Then it becomes a hundred national numbering plans with different rules.
- CPaaS providers
- Fintech and banking platforms
- Marketplaces
- CRM and messaging software
- Fraud and onboarding teams
What your customers would see
example interfaceMockupIllustrative mockup of the interface we would build. Figures shown are examples, not results from a live deployment.
The problem this solves
Phone numbers carry more weight in product flows than their simplicity suggests. They are an account identifier, a delivery address for one-time codes, a fraud signal and a contact route. A number that is unreachable, recently reassigned, or a virtual line used for abuse causes failures far downstream of the form field that accepted it.
Validation by regular expression catches formatting and nothing else. A number can be perfectly well-formed, correctly prefixed and entirely unallocated. The real questions — is this range in service, is it mobile or fixed, which carrier holds it now, is it a virtual or VoIP line — require numbering plan data and, for the carrier question, network lookups.
Here the honest answer differs by market. Some countries operate central portability databases accessible to authorised parties. Some expose nothing, and the only way to learn the current carrier is a network query with its own cost and access requirements. Several permit lookup for routing purposes but restrict other uses. Any product promising uniform global carrier data is either paying heavily for it or guessing.
Who buys this
CPaaS providers, Fintech and banking platforms, Marketplaces, CRM and messaging software, Fraud and onboarding teams
What the API returns
What comes back
- Validity against the national numbering plan, not just format
- E.164 normalisation with country and region detection
- Line type classification: mobile, fixed, VoIP, virtual, premium, toll-free
- Carrier identification where the market and permission allow it
- Portability status where a portability source is available, with the source named
- Reachability indicators for routing and one-time-code delivery decisions
- Risk indicators for disposable and virtual-number ranges commonly used in abuse
- Per-field coverage and confidence, so missing data is explicit rather than implied
Endpoints
| Method | Path | Returns |
|---|---|---|
| GET | /v1/lookup/{number} | Full intelligence for one number |
| POST | /v1/lookup/batch | Validate and enrich many numbers in one call |
| GET | /v1/lookup/{number}/carrier | Carrier and portability lookup only |
| GET | /v1/lookup/{number}/reachability | Reachability signals for delivery decisions |
| GET | /v1/coverage | What is available per country, with source and method |
| POST | /v1/feedback | Report delivery outcomes to improve reachability scoring |
Request and response
illustrativeRequest
{
"number": "+381641234567",
"default_country": "RS",
"include": ["line_type", "carrier", "portability", "reachability", "risk"],
"method": "network_lookup_if_permitted"
}Response
{
"input": "+381641234567",
"e164": "+381641234567",
"valid": true,
"country": { "iso": "RS", "dialing_code": "381" },
"line_type": { "value": "mobile", "confidence": "high",
"source": "numbering_plan" },
"carrier": {
"name": "Example Mobile RS",
"confidence": "high",
"source": "network_lookup",
"queried_at": "2026-10-22T12:04:18Z"
},
"portability": {
"status": "not_ported",
"source": "network_lookup",
"note": "No central portability register exposed in this market; status derived from network response"
},
"reachability": { "band": "good", "basis": "range_in_service" },
"risk": { "virtual_range": false, "disposable_indicators": [] },
"coverage_note": "Carrier and portability available for RS via network lookup. For 23 of 41 configured countries, portability is unavailable or restricted — see /v1/coverage."
}Where the data comes from
| Official numbering plan data | Published allocations from national regulators — authoritative for validity and range type, and free in most markets |
| Network lookup services | HLR, MNP and equivalent queries through an authorised provider; per-query cost, and permitted purposes are defined by the agreement |
| Central portability registers | Where a market operates one and grants access — clean data, but available in a minority of countries |
| Carrier prefix and range databases | Licensed reference data for markets with no live lookup, accurate at range level but stale on ported numbers |
| Your own delivery outcomes | Delivery receipts and failures from your messaging traffic, which is the best reachability signal that exists |
| Known virtual and disposable ranges | Maintained from public documentation and observed abuse patterns, useful but never complete |
The intelligence layer
The difference between a demo and a service is mostly in this section. These are the parts that keep the answer trustworthy once real traffic is hitting it.
- Numbering plan parsing per country rather than a global regular expression, because national rules differ in ways a single pattern cannot express
- Layered resolution: plan data first, then reference database, then live network lookup only where it is permitted and worth the cost
- Per-field source and confidence attached to every answer, since a carrier from a prefix table and a carrier from a network query are not the same claim
- Caching tuned per field — validity is stable for years, carrier changes with a port, reachability changes daily
- Reachability scoring calibrated against your own delivery receipts, which beats any purchased reachability indicator
- Virtual and disposable range detection from documented allocations plus observed abuse, with the basis recorded
- Coverage matrix maintained and exposed as an endpoint, because what is available per country is a moving target
- Monitoring of lookup success rates per market, since a degraded provider route looks like numbers going invalid
What it changes for the business
Fewer failed deliveries
Catching unreachable and misclassified numbers before sending removes a quiet, recurring cost.
Cleaner onboarding
Invalid and virtual numbers are rejected at the form rather than discovered during a failed verification.
Lower lookup spend
Layered resolution means a paid network query happens only when cheaper sources cannot answer.
Fraud signal
Line type and virtual-range indicators are among the cheaper useful signals available at signup.
How it fits into your product
How it embeds
- Single GET per number with sub-100ms responses for cached fields, suitable for inline form validation
- Batch endpoint for cleaning an existing contact database without hitting per-query costs unnecessarily
- Configurable method policy so you control when a paid network lookup is permitted to fire
- Delivery-outcome feedback endpoint so reachability improves from your own traffic
- Coverage endpoint your product can query, so the UI reflects what is actually knowable per country
- Deployment inside your own infrastructure where contact data cannot leave
Included in every build
- Authentication, scoped API keys and per-customer rate limiting
- Input validation with predictable, documented error responses
- Versioned endpoints so your integration never breaks without notice
- Request and response logging for audit and dispute resolution
- Latency, error-rate and usage monitoring with alerting
- OpenAPI specification, sandbox environment and client examples
- Backups, failover design and a documented recovery procedure
- An agreed support arrangement once the service is live
How we would build it
about 9 weeksDiscovery
Week 1
A short, focused scoping round: the inputs available, the output you need, expected volume and the latency budget.
Prototype on your data
Weeks 2–3
A callable endpoint running against a sample of your real records, so you can judge accuracy before committing to the full build.
Production build
Weeks 4–8
Hardening, documentation, authentication, monitoring and the throughput work needed to run this at your volume.
Integration and handover
Week 9
Integration support for your team, load testing and an agreed support arrangement.
Commercial models
There is no fixed price list, because the cost is driven by data complexity, integration count, model requirements, request volume and the support level you need. Scope is agreed in writing before development starts.
Fixed-scope prototype
A defined slice of the service, built and priced as one piece of work. The usual first step when the business case needs proving internally.
Fixed-price build
An agreed scope against a written architecture, delivered for an agreed price. Best when the requirements are already clear.
Build then retainer
We build the service, then operate and improve it under a monthly agreement covering monitoring, updates and model maintenance.
White-label product
The service runs under your brand, your domain and your pricing, with MLPivot invisible to your customers.
Questions buyers ask
Can you tell us the current carrier for any number worldwide?
No, and this is the most important thing to be clear about. It varies by market. Some countries operate a central portability register available to authorised parties, giving clean and current answers. Others expose nothing, and the only route is a network query through a provider with its own cost and permitted-purpose terms. A few restrict carrier lookup to routing use only. We publish a coverage matrix per country with the method and the limitation, rather than a single global claim.
How accurate is portability data?
Where a central register is accessible, very accurate. Where it is not, portability is inferred from a network response, which is reliable at the moment of query but not historically. In markets with neither, we return no portability status rather than a prefix-table guess — a prefix table tells you who was originally allocated the range, which for a ported number is simply wrong.
Is a network lookup legal for fraud screening?
That depends on the provider agreement and the jurisdiction. Several network lookup services permit queries for routing and delivery purposes but restrict use for profiling or screening. Those terms are checked per provider and per market during discovery, and we design the method policy so your flows cannot accidentally make a query for a purpose the agreement does not allow.
How current is the data?
Per field, and the response says so. Numbering plan validity is stable. Carrier data is as current as the lookup method allows — a live network query is current to the second, a reference database may be weeks behind on ported numbers. Reachability reflects recent observed delivery outcomes. Every field carries its source and the time it was resolved.
Does this identify who owns a number?
No. Subscriber identity is not available through these sources and we would not build toward it. The API returns characteristics of the number and its line, not information about a person.
Related blueprints
SMS Delivery Optimisation API
Route quality analytics, delivery prediction and fallback recommendations for platforms sending high volumes of messaging traffic.
SIM Swap Risk API
Authorised network-derived indicators of recent SIM or device changes, for platforms using a phone number as an authentication factor.
Network Quality Intelligence API
Coverage estimates, outage signals and connection quality measures assembled from permitted measurement data and returned as an API.
Want this built for your platform?
Tell us what your product does today and what you want another system to be able to ask it. We will come back with an approach, a scope and a price.