HLR and MNP Lookup API for smarter routing and lower SMS costs
Clean your lists, route every SMS to the right network, and stop paying for messages that will fail.
Get real-time HLR lookup results with portability, Mobile Country Code (MCC) and Mobile Network Code (MNC), number type, and, where available, the last country of use.
It's reliable delivery, predictable spend, and an API your developers can ship fast.
*No credit card required
+1,000 BUSINESSES USE SMS.to FOR THEIR needs
Why number intelligence before you send?
You deserve clear results before you pay to deliver a message. Real-time checks help you:
Stop waste
by removing unreachable or inactive numbers before a campaign
Route right
with home location register (HLR) lookup and SMS for Mobile Number Portability (MNP) so messages go to the current carrier
Protect the user journey
with fewer failed OTPs, faster signups, and fewer support tickets
What You Get in the Response
Your API response returns practical data for routing, validation, and reporting. Fields may vary by country or operator.
📡 reachable: active or inactive line
🔁 ported: whether the number moved to another network
📶 operator_name: current or original network
🌍 mcc & mnc: mobile country code + network code
🏳️ country_iso: two-letter country code
☎️ number_type: mobile, landline, or virtual
🆔 imsi: where regionally supported
✈️ roaming: roaming status where available
🌐 last_country_of_use: where available
⏱️ lookup_timestamp & latency_ms: timing + SLO info
✔️ status_code & reason: success or issue classification
Batch checks and CSV uploads are supported where enabled.
You can also run lookups directly in the dashboard and export results anytime.
If your use case depends on a specific field, tell us and we’ll confirm regional coverage first.
HLR vs MNP vs
Carrier Lookup
HLR lookup
HLR lookup gives you live status and the home network profile. Good for reachability and basic routing.
MNP lookup
MNP lookup focuses on portability so you can route to the current network in markets with heavy porting.
Carrier lookup with MCC MNC
Carrier lookup with MCC MNC gives you static mappings and formatting guidance. Good as a fallback when you do not need live status.
Built for developers who want clean, fast integration
Use our HLR and MNP service through our reliable HTTP API. Here are patterns to get moving:
curl --location 'https://hlr.sms.to/api/v2/lookup' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_key>' \
--data '{
"number": "+447704571048",
"default_prefix": "GB"
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.sms.to/sms/send',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"message": "This is test and \\n this is a new line",
"to": "+35799999999999",
"bypass_optout": true,
"sender_id": "SMSto",
"callback_url": "https://example.com/callback/handler"
}',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer <api_key>',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var https = require('follow-redirects').https;
var fs = require('fs');
var options = {
'method': 'POST',
'hostname': 'api.sms.to',
'path': '/sms/send',
'headers': {
'Authorization': 'Bearer <api_key>',
'Content-Type': 'application/json'
},
'maxRedirects': 20
};
var req = https.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
var postData = JSON.stringify({
"message": "This is test and \n this is a new line",
"to": "+35799999999999",
"bypass_optout": true,
"sender_id": "SMSto",
"callback_url": "https://example.com/callback/handler"
});
req.write(postData);
req.end();
require "uri"
require "json"
require "net/http"
url = URI("https://api.sms.to/sms/send")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <api_key>"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"message": "This is test and \n this is a new line",
"to": "+35799999999999",
"bypass_optout": true,
"sender_id": "SMSto",
"callback_url": "https://example.com/callback/handler"
})
response = https.request(request)
puts response.read_body
import http.client
import json
conn = http.client.HTTPSConnection("api.sms.to")
payload = json.dumps({
"message": "This is test and \n this is a new line",
"to": "+35799999999999",
"bypass_optout": True,
"sender_id": "SMSto",
"callback_url": "https://example.com/callback/handler"
})
headers = {
'Authorization': 'Bearer <api_key>',
'Content-Type': 'application/json'
}
conn.request("POST", "/sms/send", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"message\": \"This is test and \\n this is a new line\",\r\n \"to\": \"+35799999999999\",\r\n \"bypass_optout\": true,\r\n \"sender_id\": \"SMSto\",\r\n \"callback_url\": \"https://example.com/callback/handler\"\r\n}");
Request request = new Request.Builder()
.url("https://api.sms.to/sms/send")
.method("POST", body)
.addHeader("Authorization", "Bearer <api_key>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sms.to/sms/send"
method := "POST"
payload := strings.NewReader(`{`+"
"+`
"message": "This is test and \n this is a new line",`+"
"+`
"to": "+35799999999999",`+"
"+`
"bypass_optout": true,`+"
"+`
"sender_id": "SMSto",`+"
"+`
"callback_url": "https://example.com/callback/handler"`+"
"+`
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Authorization", "Bearer <api_key>")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
GET API KEY →
Helpful implementation notes for your engineers
- Use asynchronous processing for large jobs in your app if you need to avoid blocking flows
- Retry temporary failures safely. e.g If the API returns a temporary error like HTTP 429 or 5xx, wait and retry with backoff (for example 1s, 2s, 4s), and stop after a small number of attempts.
- Log response status and timing for your SLOs
- Idempotency keys help you avoid duplicate billing if you retry
For language examples and SDKs, see the docs and GitHub above. If you prefer a Postman collection, ask us and we’ll share the latest.
Pricing and free credits that make testing simple
You can start with a free trial. If you need HLR evaluation credits or volume pricing, talk to our team and we’ll confirm the best fit for your traffic.
Popular ways teams use lookup data
Marketing and CX
Clean lists and route messages to the right network. Reduce undelivered SMS and lower cost per conversion.
Product and growth
Improve OTP delivery for signups and password resets. Fewer retries and fewer tickets.
Fraud and risk
Combine reachability, portability, and carrier lookup with your risk signals. Spot suspicious patterns before you approve.
Operations and billing
Standardise reporting with MCC MNC codes and consistent status fields across countries.
Compliance and data handling you can trust
Coverage and reliability
What Our Users Say
Start with free credits or talk to a human
Start free and see reachability, portability, and MCC MNC in action.
Talk to an expert if you prefer a quick walkthrough with your country list and traffic profile.
FAQ
It is a real-time home location register lookup that checks if a number is reachable and identifies its network.
HLR focuses on live status and the home profile. MNP confirms if the number was ported and who the current carrier is.
IMSI lookup may be available in some regions. If you need it for a market, we will confirm availability.
Yes. MCC and MNC codes are returned where available to support accurate carrier lookup and routing.
You can start with free credits so you can test before you buy. If you need a specific allowance, ask and we will confirm.
Yes. You can upload a CSV in the dashboard to run HLR/MNP checks on a list, then reuse the cleaned list for messaging. You can also run batch lookups over the API and receive results by webhook.
Some markets use portability databases rather than live HLR. If you target a specific country, we will confirm the data source.