Latest Legacy

Overview

The Lookup API provides a way to retrieve information about a phone number. Lookup supports the following types of data.

  • Region-specific number formatting and validation
  • Carrier and service provider information
  • Portability information (only for the US and Canada)

Lookup requests cost $0.004 per request.

In this guide, we’ll see how to use Plivo APIs to look up a number from your web application. Let’s look at some prerequisites before we dive into the code.

  • Plivo Auth ID and Auth Token: You’ll find your Plivo Auth ID and Auth Token on the home screen of your Plivo console.

API URL

API Endpoint

GET https://lookup.plivo.com/v1/Number/{PhoneNumber}

The Plivo REST API is served over HTTPS to ensure data privacy. Unencrypted HTTP is not supported. {PhoneNumber} is the phone number for which you request information. Phone numbers can be specified in standard E.164 format.

Authentication

Lookup API HTTP requests are protected with HTTP Basic authentication. To learn more about how Plivo handles authentication, refer to our security documentation. In short, you use your Plivo

auth_id as the username and your

auth_token as the password for HTTP Basic authentication. You can find your

auth_id and

auth_token in the Account section of the Overview page of the Plivo console.

Content-Type

All GET request arguments must be passed in the query string.

Look Up a Phone Number

HTTP GET

Returns phone number information matching the specified request. Formatting information is standard. You can request carrier, portability information (only for the US and Canada), and phone number type information.

GET https://lookup.plivo.com/v1/Number/{PhoneNumber}

Query Parameters

The basic GET query string parameters allow you to specify the phone number you want information about and the types of information you’d like:

typeRequiredstring

The value of the parameter should be the string carrier.

We’ll be adding more phone number information in the future; at that time, additional values will be available.

Note: A successful Lookup API response will have an HTTP status code set to 200.

Example

Look up a number for the carrier information.

Example Request

1
2
3
4
5
6
7
8
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')

#Number lookup API
response = client.lookup.get("<your_number>")

print(response)

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

# Numberlookup API
begin
response = api.lookup.get('your_number')
puts response
rescue PlivoRESTError => e
    puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
let plivo = require('plivo');

let client = new plivo.Client('<auth_id>', '<auth_token>');

// Numberlookup
client.lookup.get("<your_number>")
.then(function(response) {
    console.log(response);
}).catch(function(error) {
    console.log(error);
});

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>", "<auth_token>");

$client->client->setTimeout(40);


// Numberlookup API Product
try { 
$response = $client->lookup->get("<your_number>");
print_r($response);
}
catch (PlivoRestException $ex) {
    print_r(ex);
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package test;
import java.io.IOException;
import com.plivo.api.exceptions.PlivoRestException;
public class Test {
	public static void main(String[] args) {
		Plivo.init("<auth_id>", "<auth_token>");
        //Number Lookup API
		try {
				System.out.println(com.plivo.api.models.lookup.Number
			        .getter("<your_number>")
			        .get());
		} catch (IOException e) {
				e.printStackTrace();
		} catch (PlivoRestException e) {
				e.printStackTrace();
		}
	}
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace test_apps
{
    class Program
    {
        static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");

            // Number Look Up API
            try
            {
                var response = api.Lookup.Get("<your_number>");
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

Was this code helpful

1
2
curl -i --user auth_id:auth_token \
https://lookup.plivo.com/v1/Number/{PhoneNumber}?type=carrier

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
package main

import (
	"fmt"

	plivo "github.com/plivo/plivo-go/v7"
)

func main() {

	client, err := plivo.NewClient("<auth_id>", "<auth_token>",
		&plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}

	// Numberlookup
	response, err := client.Lookup.Get("<your_number>",
		plivo.LookupParams{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

API Response

Returns a response in JSON format. An api_id is set in each response to uniquely identify the request. The API returns one of the following HTTP status codes depending on whether the API call is successful or a failure.

Response Examples

Success Response Attributes

These attributes are returned for success response:

api_idstring

Uniquely identifies the request.

phone_numberstring

The phone number that was looked up in the API request in E.164 format.

countrydict

Three key-value pairs that provide information regarding the country:

name(string): The name of the country to which this number belongs.

iso2(string): The two-letter country code defined in the ISO 3166-1 standard.

iso3(string): The three-letter country code defined in ISO 3166-1.

formatdict

Four key-value pairs that provide information regarding different number formats.

e164(string): Gives the number in E.164 format. Example : "+12045551111"

national(string): Gives the number in national format. Example : "(204) 555-1111"

international(string): Gives the number in international format. Example : "+1 204-555-1111"

rfc3966(string): Gives the number in RFC 3966 format. Example : "tel:+1-204-555-1111"

carrierdict

Contains five key-value pairs that provide information regarding the carrier of the number.

mobile_country_code(string): A three-letter string that specifies the mobile country code (MCC) of the number. For Fixed type phone numbers this is set as empty_string.

mobile_network_code(string): A two- or three-letter string that specifies the mobile network code (MNC) of the number. For Fixed type phone numbers this is set as empty_string.

name(string): The name of the carrier to which the number belongs. If the name of carrier is not found, this is set as empty_string.

type(string): The type of phone number, which may be  fixed, mobile, voip, or toll-free. If the number belongs to any other type, the value will be unknown.

ported(string): If the number is ported, then the value is yes. If the number is not ported, then the value is no. Ported information is shown only for the USA and Canada. For other countries the value is set to unknown.

resource_uristring

The URI that can be used to look up the same phone number again.

Error Response Attributes

These attributes are returned for error responses:

api_idstring

Uniquely identifies the request.

error_codeinteger

Indicates an error and provides the error code.

messagestring

Provides error information regarding the request — given only when there’s an error.

Note: Only possible numbers (for a given region, using length and prefix information) will return formatting results. For further information about error codes in error responses, refer to the Troubleshooting page.

Response

Success

{
    "api_id": "e4a25a0a-a19f-4ff6-b8b5-1841bea253f6",
    "phone_number": "+16172252821",
    "country": {
        "name": "United States",
        "iso2": "US",
        "iso3": "USA"
    },
    "format": {
        "e164": "+16172252821",
        "national": "(617) 225-2821",
        "international": "+1 617-225-2821",
        "rfc3966": "tel:+1-617-225-2821"
    },
    "carrier": {
        "mobile_country_code": "",
        "mobile_network_code": "",
        "name": "Verizon",
        "type": "fixed",
        "ported": "no"
    },
    "resource_uri": "/v1/Number/+16172252821?type=carrier"
}

Error

{
   "api_id": "<api_id>",
   "error_code": 403,
   "message": "Account is forbidden from accessing resource."
}