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