Phone
Postio phone validation parses and formats a number, then runs a live HLR carrier lookup — so you learn not just whether a number is well-formed but which carrier holds it now, whether it has been ported, and whether it is reachable.
Validate a phone number
Billable on a result. Pass the number in the path (URL-encoded; a leading + becomes %2B). Numbers in E.164 format resolve most reliably. The HLR lookup queries the mobile network directly, so like email this endpoint is slower than an address call — validate at capture, not per keystroke.
curl "https://api.postio.co.uk/v1/phone/%2B447700900123" \
-H "x-api-key: pk_..."{
"success": true,
"results": [
{
"number": "+447700900123",
"isValid": true,
"isPossible": true,
"type": "mobile",
"countryCode": "GB",
"countryName": "United Kingdom",
"nationalFormat": "07700 900123",
"internationalFormat": "+44 7700 900123",
"e164Format": "+447700900123",
"currentCarrier": "EE",
"isPorted": false,
"isReachable": true
}
],
"meta": { "countResults": 1, "requestId": "..." }
}The phone result object
| Field | Type | Description |
|---|---|---|
| number | string | The number that was checked. |
| isValid | boolean | Whether the number is a valid, dialable number. |
| isPossible | boolean | Whether the number is a possible number for its length and prefix (a weaker check than isValid). |
| type | string | null | Line type — mobile, fixed line, VoIP, etc. |
| countryCode | string | null | ISO country code the number belongs to. |
| countryName | string | null | Country name. |
| nationalFormat | string | null | Number formatted for national dialling. |
| internationalFormat | string | null | Number in international format. |
| e164Format | string | null | Number in E.164 canonical format — store this. |
| originalCarrier | string | null | The carrier the number was originally allocated to. |
| currentCarrier | string | null | The carrier that holds the number now (from the live HLR lookup). |
| isPorted | boolean | null | Whether the number has been ported away from its original carrier. |
| isReachable | boolean | null | Whether the number is currently reachable on the network. |
| mcc | string | null | Mobile Country Code of the current network. |
| mnc | string | null | Mobile Network Code of the current network. |
| level | string | null | Depth of lookup achieved for this number. |
| lookupError | string | Reason the carrier lookup could not complete, where applicable. |
Validity vs reachability
isValid tells you the number is well-formed and dialable; isReachable tells you the live network says a handset is currently on it. Use isValid to accept input, and currentCarrier / isReachable when you need to know a number will actually receive an SMS before you spend money sending one. Store the e164Format — it is the canonical, unambiguous form.
FAQ
- Does the Postio phone API do a live carrier (HLR) lookup?
- Yes. Beyond parsing and formatting the number, Postio runs a live HLR lookup against the mobile network to report the current carrier, whether the number has been ported, and whether it is currently reachable.
- How do I check if a UK mobile number can receive an SMS?
- Call GET /phone/{number} and check isReachable together with type "mobile" and currentCarrier. isValid confirms the number is well-formed; isReachable reflects the live network status, which is what tells you an SMS is likely to be delivered.
- What phone number format should I send to Postio?
- E.164 format (for example +447700900123) resolves most reliably. Pass the number URL-encoded in the path, so the leading + becomes %2B.