FAQs - Number Lookup API

1. Getting Started With The Plivo Lookup API

Plivo’s Lookup API allows users to query phone number information including number validation and formatting, carrier information, and the portability information associated with a phone number. Continue reading for an overview of the Lookup API, how it works, and answers to frequently asked questions.

This guide covers the following information:

  • Submit A Lookup API Request
  • Where Does Lookup Data Come From?
  • How Is Phone Number Validity Determined?
  • What Are The Carrier Lookup 'type' Values? 
  • Are There Geographic Support And Limitations?
  • Can I Process Simultaneous Lookup API Requests?
  • Does Lookup Cache Response Values?  

Submit A Lookup API Request

To Lookup a phone number, your application needs to make an HTTP GET request to Plivo’s Lookup REST API resource with the phone number you wish to lookup. Here's a simple cURL script example:

curl -i --user auth_id_ID:auth_token \

This example will look up to the phone number (204) 999-9999(2539999999 inline 1 of the code sample). It should return the following response:

	"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": "true_or_false"

Notice: The Lookup API will return an HTTP 404 status with a response containing "code": 20404 when a phone number is determined invalid. For full details, see the section How is phone number validity determined.

Where Does Lookup Data Come From?

Lookup utilizes a variety of authoritative sources to return the most accurate response for a given Lookup type. See more details on each Lookup type below:

Lookup type

Data sources

Update frequency

Number validation and formatting

International numbering plan data



Mobile number portability and numbering plan data from each country’s phone number regulator (where available).

Varies by country
(At a minimum every 30 min, at maximum every 24 hrs)

Portability (US & CA)

Information on if the number is ported or not

Minimum of every 24 hours

Portability (International)




How Is Phone Number Validity Determined?

The lookup will return an HTTP 404 status code if a phone number resource is invalid. 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 will file their 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 a variety of carrier partners to maintain accurate global numbering plan data but discrepancies can arise as numbering plans change and downstream providers must propagate these changes.

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 (aka 'fixed' or 'wireline') and mobile (aka 'non-fixed' or 'wireless') are service type designations provided by the carrier who owns the number.
  • VOIP is a classification of the carrier.

Please note, since VoIP phone numbers are easier to obtain, they are 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:

Can I Process Simultaneous Lookup API Requests?

The Lookup API only handles a phone number per request. For more information and recommendations, see Sending multiple requests to Plivo Lookup API.

Does Lookup Cache Response Values?

Lookup does not cache any response values.


2. Sending Multiple Requests To Plivo Lookup API

4. What Numbers Can I Get Lookup API Details For?

You can request information for any number - mobile, landline, VoIP, premium, special etc. 

5. How Are The Requests Billed?

If your request was rejected or the call back returns with the status of ‘404,’ you will not be billed. Every successful request will be charged at $0.0040 per request.

6. 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 name lookup. For more details, including usage examples, see Getting Started with the Plivo Lookup API.

See Using the API to search for and buy Plivo phone numbers for our API resources on Plivo phone numbers.

Was this article helpful?
0 out of 0 found this helpful
Didn’t find what you are looking for? Create new ticket