Get Started with Phone Numbers

    These actions can be performed with the PhoneNumber API:

    BaseURI https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/

    Prerequisites

    1. Sign up for a free Plivo trial account.
    2. Check out our server SDKs and install the SDK for the programming language you want to use.
    3. Buy a Plivo phone number. You need a Plivo phone number to receive calls. You can buy a Plivo phone number in more than 20 countries by visiting Phone Numbers > Buy Numbers in the Plivo console. Check the Voice API coverage page to see the supported countries.
    4. Use a web hosting service to host your web application. Many inexpensive cloud hosting providers charge just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

    Search for New Numbers

    This API call lets you search for fixed, mobile, and toll-free numbers available on Plivo. You can search on any combination of the two-letter country code, number pattern, number type, and region. The call returns a list of numbers that match the search criteria and that are available to rent.

    GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
    auth_id = "Your AUTH_ID"
    auth_token = "Your AUTH_TOKEN"
    
    p = plivo.RestAPI(auth_id, auth_token)
    
    # Search for new number
    params = {
        'country_iso': 'US', # The ISO code A2 of the country
        'type' : 'local', # The type of number you are looking for. The possible number types are local, national and tollfree.
        'pattern' : '210', # Represents the pattern of the number to be searched. 
        'region' : 'Texas' # This filter is only applicable when the number_type is local. Region based filtering can be performed.
    }
    
    response = p.search_phone_numbers(params)
    print str(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    require 'rubygems'
    require 'plivo'
    include Plivo
    
    AUTH_ID = "Your AUTH_ID"
    AUTH_TOKEN = "Your AUTH_TOKEN"
    
    
    p = RestAPI.new(AUTH_ID, AUTH_TOKEN)
    
    # Search for new number
    params = {
        'country_iso' => 'US', # The ISO code A2 of the country
        'type' => 'local', # The type of number you are looking for. The possible number types are local, national and tollfree.
        'pattern' => '210', # Represents the pattern of the number to be searched. 
        'region' => 'Texas' # This filter is only applicable when the number_type is local. Region based filtering can be performed.
    }
    
    response = p.search_phone_number(params)
    print response
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
    var plivo = require('plivo');
    var p = plivo.RestAPI({
      authId: 'Your AUTH_ID',
      authToken: 'Your AUTH_TOKEN'
    });
    
    // Search for new number
    var params = { 
        'country_iso': 'US', // The ISO code A2 of the country
        'type' : 'local', // The type of number you are looking for. The possible number types are local, national and tollfree.
        'pattern' : '210', // Represents the pattern of the number to be searched. 
        'region' : 'Texas' // This filter is only applicable when the number_type is local. Region based filtering can be performed.
    };
    
    p.search_phone_numbers(params, function (status, response) {
        console.log('Status: ', status);
        console.log('API Response:\n', response);
    });
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    <?php
        require 'vendor/autoload.php';
        use Plivo\RestAPI;
        
        $auth_id = "Your AUTH_ID";
        $auth_token = "Your AUTH_TOKEN";
        
        $p = new RestAPI($auth_id, $auth_token);
        
        # Search for new number
        $params = array(
            'country_iso' => 'US', # The ISO code A2 of the country
            'type' => 'local', # The type of number you are looking for. The possible number types are local, national and tollfree.
            'pattern' => '210', # Represents the pattern of the number to be searched. 
            'region' => 'Texas' # This filter is only applicable when the number_type is local. Region based filtering can be performed.
        );
        $response = $p->search_phone_numbers($params);
        print_r ($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
    27
    28
    29
    30
    31
    32
    
    package plivoexample;
    
    import java.util.LinkedHashMap;
    
    import com.plivo.helper.api.client.*;
    import com.plivo.helper.api.response.number.NumberSearchFactory;
    import com.plivo.helper.exception.PlivoException;
    
    public class App {
    
        public static void main(String[] args) throws IllegalAccessException {
    
            String auth_id = "Your AUTH_ID";
            String auth_token = "Your AUTH_TOKEN";
            
            RestAPI api = new RestAPI(auth_id, auth_token, "v1");
    
            // Search for a phone number
            LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
            parameters.put("country_iso","US");
            parameters.put("type","local");
            parameters.put("pattern","210");
            parameters.put("region","Texas");
    
            try {
                PhoneNumberSearchFactory resp = api.searchPhoneNumber(parameters);
                System.out.println(resp);
            }catch (PlivoException e){  
                System.out.println(e.getLocalizedMessage());
            } 
        }
    }
    
    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 RestSharp;
    using Plivo.API;
    
    namespace apps
    {
        class Program
        {
            static void Main(string[] args)
            {
                RestAPI plivo = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");
                
                // Search for a new phone number
                IRestResponse<PhoneNumberList> resp = plivo.search_phone_numbers(new Dictionary<string,string>()
                {
                    {"country_iso","US"}, // The ISO code A2 of the country
                    {"type","local"}, // The type of number you are looking for. The possible number types are local, national and tollfree.
                    {"pattern","210"}, // Represents the pattern of the number to be searched.
                    {"region","Texas"} // This filter is only applicable when the number_type is local. Region based filtering can be performed.
                });
    
                Console.WriteLine(resp.Content);
            }
        }
    }
    
    1
    2
    
    curl -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/?country_iso=US&type=local&pattern=210&region=Texas
    

    Rent a Number

    You can use a number you retrieve from the search above as input to rent the number for your Plivo account. Upon successful execution, the number will appear in your Plivo dashboard and be available for all the actions in the Number API.

    POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/{number}/

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    
    import plivo
    
    auth_id = "Your AUTH_ID"
    auth_token = "Your AUTH_TOKEN"
    
    p = plivo.RestAPI(auth_id, auth_token)
    
    params = {
        'number' : '444444444444' # Phone number to buy
    }
    
    response = p.buy_phone_number(params)
    print str(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
    require 'rubygems'
    require 'plivo'
    include Plivo
    
    AUTH_ID = "Your AUTH_ID"
    AUTH_TOKEN = "Your AUTH_TOKEN"
    
    
    p = RestAPI.new(AUTH_ID, AUTH_TOKEN)
    
    # Get a particular number
    params = {
        'number' => '444444444444' # Phone number to buy
    }
    
    response = p.buy_phone_number(params)
    print response
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
    var plivo = require('plivo');
    var p = plivo.RestAPI({
      authId: 'Your AUTH_ID',
      authToken: 'Your AUTH_TOKEN'
    });
    
    // Buy a phone number
    var params = { 
        'number' : '444444444444' // Phone number to buy
    };
    
    p.buy_phone_number(params, function (status, response) {
        console.log('Status: ', status);
        console.log('API Response:\n', response);
    });
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
    <?php
        require 'vendor/autoload.php';
        use Plivo\RestAPI;
        
        $auth_id = "Your AUTH_ID";
        $auth_token = "Your AUTH_TOKEN";
        
        $p = new RestAPI($auth_id, $auth_token);
        
         # Get a particular number
        $params = array(
                'number' => '444444444444' # Phone number to buy
            );
        $response = $p->buy_phone_number($params);
        print_r ($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
    27
    28
    29
    
    package plivoexample;
    
    import java.util.LinkedHashMap;
    
    import com.plivo.helper.api.client.*;
    import com.plivo.helper.api.response.number.NumberResponse;
    import com.plivo.helper.exception.PlivoException;
    
    public class App {
    
        public static void main(String[] args) throws IllegalAccessException {
    
            String auth_id = "Your AUTH_ID";
            String auth_token = "Your AUTH_TOKEN";
            
            RestAPI api = new RestAPI(auth_id, auth_token, "v1");
    
            // Get details of a number
            LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
            parameters.put("number","444444444444"); // Phone number to buy
            
            try{
                NumberResponse resp = api.buyPhoneNumber(parameters);
                System.out.println(resp);
            }catch (PlivoException e){  
                System.out.println(e.getLocalizedMessage());            
            }
        }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    using System;
    using System.Collections.Generic;
    using RestSharp;
    using Plivo.API;
    
    namespace apps
    {
        class Program
        {
            static void Main(string[] args)
            {
                RestAPI plivo = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");
                
                // Get a particular number
                IRestResponse<PhoneNumberResponse> res = plivo.buy_phone_number(new Dictionary<string, string>()
                {
                    {"number","444444444444"} // Phone number to buy
                });
    
                Console.WriteLine(res.Content);
            }
        }
    }
    
    1
    2
    3
    
    curl -X POST -i --user AUTH_ID:AUTH_TOKEN 
        -H "Content-Type: application/json"  
        https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/444444444444/
    

    Next Step

    Learn how to query the Pricing API.