Overview
Number lookup provides real-time carrier information, porting status, and number type validation using HLR (Home Location Register) and MNP (Mobile Number Portability) queries.
What you get:
- Carrier name and network codes (MCC/MNC)
- Porting status (original vs current carrier)
- Number type (mobile, landline, VoIP)
- Country and region information
Single Lookup
curl -X POST https://api-message.nativehub.live/api/v1/numbers/lookup \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+8801712345678"
}'
const response = await fetch('https://api-message.nativehub.live/api/v1/numbers/lookup', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
phone: '+8801712345678'
})
});
const data = await response.json();
console.log(data);
import requests
response = requests.post(
'https://api-message.nativehub.live/api/v1/numbers/lookup',
headers={
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
json={'phone': '+8801712345678'}
)
data = response.json()
print(data)
{
"phone": "+8801712345678",
"country_code": "BD",
"country_name": "Bangladesh",
"carrier": "Grameenphone",
"is_ported": false,
"is_mobile": true,
"mcc": "470",
"mnc": "01"
}
Batch Lookup
Process multiple numbers in a single request.
curl -X POST https://api-message.nativehub.live/api/v1/numbers/lookup/batch \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"numbers": ["+8801712345678", "+8801812345679", "+8801912345680"]
}'
const response = await fetch('https://api-message.nativehub.live/api/v1/numbers/lookup/batch', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
numbers: ['+8801712345678', '+8801812345679', '+8801912345680']
})
});
const results = await response.json();
response = requests.post(
'https://api-message.nativehub.live/api/v1/numbers/lookup/batch',
headers={
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
json={'numbers': ['+8801712345678', '+8801812345679', '+8801912345680']}
)
results = response.json()
Lookup History
Retrieve past lookup results.
curl -X GET https://api-message.nativehub.live/api/v1/numbers/lookup \
-H "Authorization: Bearer YOUR_API_TOKEN"
curl -X GET https://api-message.nativehub.live/api/v1/numbers/lookup/+8801712345678 \
-H "Authorization: Bearer YOUR_API_TOKEN"
Use Cases
| Use Case | Benefit |
|---|
| Pre-send validation | Avoid sending to invalid or inactive numbers |
| Contact list cleaning | Remove landlines and non-mobile numbers from SMS campaigns |
| Cost optimization | Route messages through cheapest carrier based on current network |
| Fraud prevention | Detect VoIP numbers or suspicious porting patterns |
| Analytics | Track carrier distribution in your contact database |
Lookup results are cached for 24 hours. Numbers may port between carriers, so periodic re-validation is recommended for critical use cases.
Response Fields
| Field | Type | Description |
|---|
phone | string | Phone number in E.164 format |
country_code | string | ISO 3166-1 alpha-2 country code |
country_name | string | Full country name |
carrier | string | Current carrier/operator name |
is_ported | boolean | Whether number has been ported to a different carrier |
is_mobile | boolean | Whether number is a mobile device (vs landline/VoIP) |
mcc | string | Mobile Country Code |
mnc | string | Mobile Network Code |
