The Lookup API provides a way to retrieve information about a phone number. Lookup supports the following types of data.
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.
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.
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.
All GET request arguments must be passed in the query string.
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}
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. |
Look up a number for the carrier information.
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
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.
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. |
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. |
{
"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"
}
{
"api_id": "<api_id>",
"error_code": 403,
"message": "Account is forbidden from accessing resource."
}