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 Helper Libraries 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/

Sample Response

(200, {
        u'meta': {
            u'previous': None, 
            u'total_count': 2, 
            u'offset': 0, 
            u'limit': 20, 
            u'next': None
        }, 
        u'objects': [
            {
                u'voice_enabled': True, 
                u'application': None, 
                u'region': u'California, UNITED STATES', 
                u'number': u'+11111111111', 
                u'sub_account': None,   
                u'alias': u'', 
                u'monthly_rental_rate': u'0.80000', 
                u'carrier': u'Plivo', 
                u'sms_rate': u'0.00000', 
                u'number_type': u'local', 
                u'voice_rate': u'0.00850', 
                u'sms_enabled': True, 
                u'added_on': u'2014-10-28', 
                u'resource_uri': u'/v1/Account/XXXXXXXXXXXX/Number/11111111111/'
            }, 
            {
                u'voice_enabled': True, 
                u'application': u'/v1/Account/XXXXXXXXXXXX/Application/26469261154421101/', 
                u'region': u'UNITED KINGDOM', 
                u'number': u'+444444444444 ', 
                u'sub_account': None, 
                u'alias': None, 
                u'monthly_rental_rate': u'0.80000', 
                u'carrier': u'Plivo', 
                u'sms_rate': u'0.00000', 
                u'number_type': u'local', 
                u'voice_rate': u'0.00500', 
                u'sms_enabled': True, 
                u'added_on': u'2014-12-04', 
                u'resource_uri': u'/v1/Account/XXXXXXXXXXXX/Number/444444444444/'
            }
        ], 
        u'api_id': u'c51cd630-8a8d-11e4-b153-22000abcaa64'
    }
)

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/

Sample Response

(200, {
        u'voice_enabled': True, 
        u'application': u'/v1/Account/XXXXXXXXXXXX/Application/26469261154421101/', 
        u'region': u'UNITED KINGDOM', 
        u'number': u'444444444444', 
        u'api_id': u'855ad4b0-8a8e-11e4-b153-22000abcaa64', 
        u'sub_account': None, 
        u'alias': None, 
        u'monthly_rental_rate': u'0.80000', 
        u'carrier': u'Plivo', 
        u'sms_rate': u'0.00000', 
        u'number_type': u'local', 
        u'voice_rate': u'0.00500', 
        u'sms_enabled': True, 
        u'added_on': u'2014-12-04', 
        u'resource_uri': u'/v1/Account/XXXXXXXXXXXX/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/

Sample Response

(202, {
        u'message': u'changed',
        u'api_id': u'e13fcf9a-8a90-11e4-b423-22000ac8a2f8'
    }
)

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

Sample Response

(202, {
        u'message': u'changed',
        u'api_id': u'4b342d2e-8a91-11e4-96e3-22000abcb9af'
    }
)

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

Sample Response

(202, {
        u'message': u'changed',
        u'api_id': u'6b70316e-8a91-11e4-a2d1-22000ac5040c'
    }
)

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/

Sample Response

Sample successful output
(204, '')

Sample unsuccessful output
(404, {
        u'api_id': u'7c33ff78-8f53-11e4-b932-22000ac50fac', 
        u'error': u'not found'
    }
)

Next Step

Learn how to Search and Rent Phone Numbers.

  1. Account API
  2. Application API
  3. Endpoint API
  4. Number API
  5. Phone Number API
  6. Pricing API
  7. API Pagination