Get Started with Lookup API

    Overview

    Lookup API helps you with phone number formatting and to retrieve additional information that will help you to increase the lead conversion for your business. As such, non-formatted numbers can become invalid, and the messages/calls will fail in such cases but using lookup API, you can avoid such scenarios by formatting the number before sending SMS/MMS messages or making voice calls. Please check the below prerequisites to get started with the Lookup API.

    • Sign up for a Plivo trial account.
    • Check out our server SDKs page and install the right helper based on the programming language you want to use.
    • Have a phone number you want to look up for.

    Sign up for a Plivo Account

    You can sign up with Plivo and start with a free trial account to experiment with and learn about our services. This free trial account comes with free credits. If you wish to continue with our service, you can add more credits and buy a number by clicking here. Add a number and credits to your account to test the full range of our voice and SMS service features.

    Sign up here to get your free Plivo account today.

    Follow these steps to sign up for a free trial account:

    1. Sign up with your work email address
    2. Check your inbox for an activation email from Plivo. Click on the link in the email to activate your account.
    3. Enter your mobile number to complete the phone verification step.

    Sign up with your work email address

    Sign up with email addres

    If you have any issues creating a Plivo account, please reach out to our Support Team for help.

    Looking Up a Number

    Lookup allows you to obtain information about phone numbers. With Lookup, you can identify local number formats and reduce the likelihood of undelivered messages.

    Plivo provides a simple API that allows you to lookup a phone number. Lookup requests cost $0.004 per request. It enables you to identify phone number types (mobile, fixed, VoIP and toll-free) and also the service provider of the phone number, including ported numbers(portability information limited to the US and CA).

    Code

    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)

    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

    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);
});

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

    <?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);
}

    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();
		}
	}
}

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

    package main

import (
	"fmt"

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

func main() {

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

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

    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);
            }
        }
    }
}

    1
2

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

    Sample 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."
}