Get Started with Lookup API

Overview

Lookup API helps you format phone numbers and retrieve additional information before sending SMS and MMS messages or making voice calls. Unformatted numbers may be invalid, which can cause calls and messages to fail. With Lookup, you can identify local number formats and reduce the likelihood of undelivered messages. Here’s how to get started with the Lookup API.

Sign up for a Plivo account

If you’re not already a Plivo customer, you can sign up for a free trial account to experiment with and learn about our services. Be sure to sign up with your work email address and not one from a generic email provider. Each trial account comes with free credits. You can add more credits and buy a phone number to test the full range of our voice and SMS service features.

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

Once you have an account, read about our server SDKs and install the one for the programming language you want to use.

Looking up a number

Lookup API enables you to identify phone number types (mobile, fixed, VoIP, and toll-free) and the service provider of the phone number, including ported numbers in the US and Canada.

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

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