Check carrier and live line status with one API
The request validates format, line type and carrier with Telnyx. When you need a mobile line’s current status, add HLR with live:true.
What you get
E.164 normalization
We normalize to international format (+54911...) so the rest of your system works with a consistent format.
Country by prefix or default
If it comes with +, we use the prefix. If not, use the country parameter so we interpret it as that country.
Real line type
Mobile, landline, consumer VoIP (second-number apps), business VoIP, toll-free, premium rate, with disposable-VoIP detection.
Carrier (Telnyx)
Real carrier, portability (ported from original to another) and mobile network codes MCC/MNC where applicable.
Live line (HLR)
Real-time query to the mobile network: connected/absent/unknown + roaming and current network.
Suspicious patterns
Repeated digits (111111), sequences (123456), keypad (258014), low entropy — typical fake data.
WhatsApp probability
Estimate by line type and region. Not a WhatsApp query; it is a signal, not confirmation.
Personal blacklist
Add unwanted numbers to your list; they are cut off before querying the provider and are not charged.
How it works
Normalization
We convert the number to E.164 using the international prefix or the default country you pass.
Format validation
Country numbering rules + suspicious patterns (repeated, keypad, low entropy). If invalid, no charge.
Carrier lookup
For valid numbers, we query Telnyx for carrier, portability, line type and MCC/MNC when available.
Live line (optional)
If you request live:true, Neutrino does the HLR query to the mobile network: connected/absent/unknown + roaming. Mobile only; landlines and VoIP are not charged.
In code
cURLcurl -X POST https://api.byebouncer.com/api/v1/verify-phone \ -H "Authorization: Bearer $BYEBOUNCER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone":"+5491141235678","live":true}'
Node / TypeScriptimport { ByeBouncer } from '@bye_bouncer/sdk'; const bb = new ByeBouncer({ apiKey: process.env.BYEBOUNCER_API_KEY! }); const scored = await bb.verifyPhone('+5491141235678'); console.log(scored.status, scored.carrier);
Choose the depth of your check
| Carrier (3 cr) | Carrier + HLR (up to 9 cr) | |
|---|---|---|
| E.164 format and country | Yes | Yes |
| Line type | Yes | Yes |
| Real carrier | Yes | Yes |
| Portability | Yes | Yes |
| 0-100 score | Yes | Yes |
| Suspicious patterns | Yes | Yes |
| Current mobile status | No | Yes, when available |
Frequently asked questions
What does the carrier lookup include?
We validate format and country first. For valid numbers, we query Telnyx and return carrier, portability, line type and a quality score. This costs 3 credits.
When should I add HLR?
Before calling or messaging a mobile when you need its current line status. Send live:true; HLR may add up to 6 credits when applicable.
Does live line work for landlines or VoIP?
No. HLR is a mobile network protocol. For landlines we return "fixed_line" (not charged), for VoIP "voip" (not charged). For mobile we return connected/absent/unknown with portability and roaming details.
What does "on and reachable" exactly mean?
The mobile network sees the device registered and reachable right now. It does not mean the person will answer or that the number belongs to them; it is an infrastructure check, not an intent check.
If the phone is off, is it fake?
No. We return "absent": the number is real but the device is off or out of coverage now. Try again later instead of discarding the contact.
How long does a live line query take?
The HLR lookup depends on the carrier network and can take longer than format validation or carrier lookup. Set your integration timeout for your use case.
Do you support WhatsApp?
We give a WhatsApp probability estimate based on line type and region ("likely", "possible", "unlikely"). We do not query WhatsApp — for active confirmation you need a BSP provider.
What about invalid numbers?
Numbers that do not match the country format are not even queried to the carrier and are not charged. Numbers on your personal blacklist are not charged either: they are cut off before.
Can I have my own blacklist?
Yes. Add numbers to your blacklist from the dashboard or API; any query on those numbers returns "no" without hitting the provider and without charging.
Do you charge for cached results?
Yes, same as other services. If you repeat the query within minutes we serve the stored result and show the last-check timestamp — same price as fresh.
Try it with 500 free credits
No credit card. Start using the API as soon as you sign up.
Create account