Number API

    The following actions can be performed with the Number API

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

    Prerequisites

    1. Sign up for a free Plivo trial account.
    2. Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
    3. Buy a Plivo phone number. A phone number is required to receive calls. You can buy a Plivo phone number in over 20+ countries through the Buy Numbers tab on your Plivo account UI. Check the Voice API coverage page for all the supported countries.
    4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

    List All Rented Numbers

    This API call returns a list with the details of all numbers rented under your Plivo account.

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

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
    import plivo
    
    auth_id = "Your AUTH_ID"
    auth_token = "Your AUTH_TOKEN"
    
    p = plivo.RestAPI(auth_id, auth_token)
    
    # Get all numbers
    
    params = {
        'limit' : '10',
        'offset' : '0'
    }
    response = p.get_numbers()
    print str(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
    require 'rubygems'
    require 'plivo'
    include Plivo
    
    AUTH_ID = "Your AUTH_ID"
    AUTH_TOKEN = "Your AUTH_TOKEN"
    
    
    p = RestAPI.new(AUTH_ID, AUTH_TOKEN)
    
    # Get all numbers
    params = {
        'limit' => '10', # Used to display the number of results per page.
        'offset' => '0' # Denotes the number of value items by which the results should be offset. 
    }
    
    response = p.get_numbers(params)
    print response
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    var plivo = require('plivo');
    var p = plivo.RestAPI({
      authId: 'Your AUTH_ID',
      authToken: 'Your AUTH_TOKEN'
    });
    
    // Get details of all numbers
    var params = { 
        'limit' : '10',
        'offset' : '0'
    };
    
    p.get_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);
        
        # Get all numbers
        $params = array(
                'limit' => '10', # Used to display the number of results per page.
                'offset' => '0' # Denotes the number of value items by which the results should be offset. 
            );
        
        $response = $p->get_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
    
    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");
    
            // Get all numbers
            LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
            parameters.put("limit","10"); // Used to display the number of results per page. 
            parameters.put("offset","0"); // Denotes the number of value items by which the results should be offset. 
            
            try{
                NumberSearchFactory resp = api.getNumbers(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 all numbers
                IRestResponse<NumberList> resp = plivo.get_numbers(new Dictionary<string, string>(){ 
                    {"limit", "10"}, // The number of results per page
                    {"offset", "0"}, // The number of value items by which the results should be offset
                });
    
                Console.WriteLine(resp.Content);
            }
        }
    }
    
    1
    2
    
    curl -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/Number/
    

    Get Details of a Rented Number

    This API call returns the details of a single number rented under your Plivo account.

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

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    import plivo
    
    auth_id = "Your AUTH_ID"
    auth_token = "Your AUTH_TOKEN"
    
    p = plivo.RestAPI(auth_id, auth_token)
    
    // Get details of a single number
    params = {
        'number' : '444444444444' # PHone number for which the details have to be retrieved
    }
    
    response = p.get_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 details of a single number
    params = {
        'number' => '444444444444' # Phone number for which the details have to be retrieved
    }
    
    response = p.get_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'
    });
    
    // Get details of a single number
    var params = { 
        'number' : '444444444444' // Phone number for which the details have to be retrieved
    };
    
    p.get_number_details(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 details of a single number
        $params = array(
                'number' => '444444444444' # PHone number for which the details have to be retrieved
            );
        $response = $p->get_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.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");
    
            // Get details of a single number
            LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
            parameters.put("number","444444444444"); // Phone number for which the details have to be retrieved 
            
            try{
                Number resp = api.getNumber(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 details of a single number
                IRestResponse<Number> res = plivo.get_number(new Dictionary<string, string>()
                {
                    {"number","444444444444"} // Phone number for which the details have to be retrieved
                });
    
                Console.WriteLine(res.Content
            }
        }
    }
    
    1
    2
    
    curl -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/Number/444444444444/
    

    Edit a Number

    This API call enables you to change the application and subaccount associated with a number you rented.

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

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
    import plivo
    
    auth_id = "Your AUTH_ID"
    auth_token = "Your AUTH_TOKEN"
    
    p = plivo.RestAPI(auth_id, auth_token)
    
    # Modify a number
    params = {
            'number' : '11111111111', # Number that has to be modified
            'alias' : 'testing' # The textual name given to the number
    }
    
    response = p.modify_number(params)
    print str(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    require 'rubygems'
    require 'plivo'
    include Plivo
    
    AUTH_ID = "Your AUTH_ID"
    AUTH_TOKEN = "Your AUTH_TOKEN"
    p = RestAPI.new(AUTH_ID, AUTH_TOKEN)
    
    # Modify a number
    params = {
        'number' => '11111111111', # Number that has to be modified
        'alias' => 'testing' # The textual name given to the number
    }
    
    response = p.modify_number(params)
    puts str(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    var plivo = require('plivo');
    var p = plivo.RestAPI({
      authId: 'Your AUTH_ID',
      authToken: 'Your AUTH_TOKEN'
    });
    
    // Modify a number
    var params = { 
        'number' : '11111111111', // Number that has to be modified
        'alias' : 'testing' // The textual name given to the number
    };
    
    p.edit_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
    18
    
    <?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);
        
        // Modify alias of a number
        $params = array(
                'number' => '11111111111', # Phone number for which the details have to be retrieved
                'alias' => 'testing' # The textual name given to the number
            );
        $response = $p->modify_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
    30
    
    package plivoexample;
    
    import java.util.LinkedHashMap;
    
    import com.plivo.helper.api.client.*;
    import com.plivo.helper.api.response.account.SubAccount;
    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");
    
            // Modify a number
            LinkedHashMap<String, String> params = new LinkedHashMap<String, String>();
            params.put("number","11111111111"); // Number that has to be modified
            params.put("alias","testing"); // The textual name given to the number
            
            try {
                GenericResponse resp = api.editNumber(params);
                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
    
    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");
                
                // Modify a number
                IRestResponse<GenericResponse> res = plivo.modify_number(new Dictionary<string, string>()
                {
                    {"numebr","11111111111"}, // Number that has to be modified
                    {"alias","testing"} // The textual name given to the number
                });
    
                //Prints the response
                Console.Write(res.Content);
            }
        }
    }
    
    1
    2
    3
    4
    
    curl -i --user AUTH_ID:AUTH_TOKEN 
        -H "Content-Type: application/json" 
        -d '{"alias": "testing"}'  
        https://api.plivo.com/v1/Account/{auth_id}/Number/11111111111/
    

    This API call enables you to link an application to a number you rented.

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

    Code

    This API call enables you to link an application to a number you rented.

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

    Code

    Relinquish a Number

    This API lets you relinquish a number on Plivo. Upon successful execution, the number will no longer be usable or accessible from your Plivo account. This operation cannot be undone.

    DELETE https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    import plivo
    
    auth_id = "Your AUTH_ID"
    auth_token = "Your AUTH_TOKEN"
    
    p = plivo.RestAPI(auth_id, auth_token)
    
    # Unrent a number
    params = {
        'number' : '1111111111' # Number that has to be unrented
    }
    
    response = p.unrent_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)
    
    # Unrent a number
    params = {
            'number' => '1111111111' # Number that has to be unrented
    }
    
    response = p.unrent_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'
    });
    
    // Unrent a number
    var params = { 
        'number' : '1111111111', // Number that has to be unrented
    };
    
    p.unrent_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
    
    <?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);
        
        # Unrent a number
        $params = array(
            'number' => '1111111111' # Number that has to be unrented
        );
        $response = $p->unrent_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.response.GenericResponse;
    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");
    
            // Unrent a phone number
            LinkedHashMap<String, String> param = new LinkedHashMap<String, String>();
            param.put("number","1111111111");
            
            try {
                GenericResponse resp = api.unRentNumber(param);
                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");
                
                // Unrent a number
                IRestResponse<GenericResponse> response = plivo.unrent_number(new Dictionary<string, string>()
                {
                    {"number","1111111111"} // Number that has to be unrented
                });
    
                Console.WriteLine(response.Content);
            }
        }
    }
    
    1
    2
    
    curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/Number/1111111111/
    

    Next Step

    Learn how to Search and Rent Phone Numbers.