1. Does Plivo have an API to get information about phone numbers?
Yes, with Plivo’s Lookup API you can find the proper local and E.164 phone number formatting, carrier information, and a caller ID names. For details, including usage examples, see Getting started with the Plivo Lookup API below.
See our getting started guide for Plivo phone numbers for API resources on Plivo phone numbers.
2. Getting started with the Plivo Lookup API
Plivo’s Lookup API lets developers query phone number information, including number validation and formatting, carrier information, and portability information associated with a phone number. This guide answers some common questions:
How can I submit a Lookup API request?
To look up a phone number, your application needs to make an HTTP GET request to Plivo’s Lookup API resource with the phone number you wish to look up. Here's a simple cURL script example:
curl -i --user auth_id_ID:auth_token \
https://api.plivo.com/v1/LookupNumber/{number}?info=serviceprovider
If you were to look up the phone number (204) 999-9999, for example, the Lookup API would return a response like:
{
"api_id": "ac073f08-xxxx-xxxx-xxxx-c19435b84cd7",
"country": {
"name": "Canada",
"code_iso2": "CA",
"code_iso3": "CAN"
},
"number_format": {
"e164": "+12049999999",
"national": "(204) 999-9999",
"international": "+1 204-999-9999",
"rfc3966": "tel:+1-204-999-9999"
},
"service_provider": {
"mobile_country_code": "XXX",
"mobile_network_code": "XXX",
"name": "Carrier Name",
"type": "Number_type",
"ported": "false"
}
}
In some cases, we do not have or can’t share information about portability status. In those cases, the Lookup API completes successfully with a response that contains "ported": "unknown".
If the value of ported in “unknown,” the carrier name value returned is unreliable, since we don't know whether the carrier continues to service this number.
The Lookup API will return an HTTP 404 status with a response that contains "code": 20404 when a phone number is determined invalid. See the section below on how Plivo determines phone number validity.
Where does Lookup data come from?
Lookup utilizes a variety of authoritative sources to return the most accurate response for a given Lookup type.
|
Lookup Type
|
Data Sources
|
Update Frequency
|
|
Number validation and formatting
|
International numbering plan data
|
Real-time
|
|
Carrier
|
Mobile number portability and numbering plan data from each country’s phone number regulator (where available)
|
Varies by country —
minimum every 30 minutes, maximum every 24 hours
|
|
Portability
(US and CA)
|
We don’t offer portability data
|
NA
|
|
Portability (international)
|
Provided at additional cost
|
Varies by country
|
How does Plivo determine phone number validity?
Phone number validity is based on international phone numbering plan data administered by the ITU. Though the ITU should in theory have all global numbering plans on file, in practice, not every country files its numbering plans with the ITU. Additionally, some government authorities may let telecom companies be responsible for administrating numbering plans. As a result of this lack of centralization, maintaining an accurate global numbering plan is a patchwork process. Plivo works with carrier partners to maintain accurate global numbering plan data, but discrepancies can arise as numbering plans change and downstream providers must propagate these changes.
Lookup will return an HTTP 404 status code if a phone number resource is invalid.
What are the Carrier Lookup type values?
In the response for a Carrier Lookup, the type property specifies whether the phone is a landline, mobile, or VoIP phone.
- Landline (also called fixed or wireline) and mobile (or non-fixed or wireless) are service type designations provided by the carrier that owns the number.
- VoIP is a classification of the carrier.
VoIP phone numbers are easier to obtain, so they're sometimes used for fraudulent purposes. Customers often use Lookup to screen these numbers in their applications.
Are there geographic support limitations?
While the Lookup API is supported internationally, there are limitations to some request types:
Phone number validation and formatting: Number validation and formatting lookups are supported in all countries worldwide.
Carrier Lookup: This is supported worldwide with the following caveats:
-
The VoIP type will be returned only for carriers in the US. It is not supported outside of the US.
-
The mobile and landline types can be returned for all countries worldwide.
-
We return values in the mobile_country_code and mobile_network_code fields for 90+ countries where mobile number portability is supported. While MCC and MNC have wide international adoption, there are cases where mobile carriers are not associated with an MCC or MNC. When you perform a Carrier search via the Lookup API, Plivo returns this information if it’s available.
-
We do not offer portability data in the US and Canada.
Can I process simultaneous Lookup API requests?
The Lookup API handles only one phone number per request. For more information and recommendations, see Sending multiple requests to the Plivo Lookup API.
Does Lookup cache response values?
Lookup does not cache any response values.
3. Sending multiple requests to the Plivo Lookup API
4. Why do the mobile country code (MCC) and mobile network code (MNC) not show up for my Plivo phone number Lookup API call?
Mobile country code (MCC) and mobile network code (MNC) are often used to help identify a mobile phone number's carrier. While MCC and MNC have wide international adoption, there are cases where mobile carriers are not associated with an MCC or MNC. When you perform a Carrier search via the Lookup API, Plivo will return this information if it's available.
5. What numbers can I get Lookup API details for?
You can request information for any number — mobile, landline, VoIP, premium, or special.
6. How are Lookup API requests billed?
Every successful request is charged at $0.0040 per request. If your request is rejected or the callback returns with a 404 status, you will not be billed.
