A dead number parses fine
valid answers whether a number could exist. live answers whether it does. GET /hlr asks the network, which keeps the only current list.
A dead number looks perfect. Ten digits, a real area code, a block the numbering plan handed out years ago. Every parser on earth calls it valid.
GET /hlr/+13102858000
{
"phone": "+13102858000",
"valid": true,
"country": "US",
"live": true,
"connected": null,
"roaming": null,
"roaming_network": null,
"roaming_country": null,
"network": null,
"original_network": null,
"mcc": null,
"mnc": null
}
valid is a math answer. The numbering plan says this string is a number that could exist, and /phone reads that plan. What the plan cannot see is whether anyone still pays the bill. live is the network's answer to that question: this number is assigned to a subscriber right now. A disconnected line comes back live false, and no amount of parsing would have told you.
Landlines answer too
connected is a different question, whether the handset is reachable this second. A landline has no handset to page, so it answers live and leaves connected null. Mobiles answer both. The extras fill in on live network queries outside North America and stay null when a dip did not answer them.
Try it
One lookup per number, 50 free a month, worldwide. GET /hlr on anything you were about to dial. The network knew the whole time. You just never asked.