Get Started with Account Phone Numbers

The following actions can be performed with the Number API

List All Rented Numbers
Get Details of a Rented Number
Edit a Number
Link an Application to a Number
Unlink an Application from a Number
Relinquish a Number

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

Prerequisites

Sign up for a free Plivo trial account.
Check out our server SDKs page and install the right helper based on the programming language you want to use.
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.
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/

Link an Application to a Number

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

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)

# Link an application to a number
params = {
        'number' : '444444444444', # Number that has to be linked to an application
        'app_id' : '16638156474000802' # Application ID that has to be linked
}

response = p.link_application_number(params)
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)

# Link an application to a number
params = {
        'number' => '444444444444', # Number that has to be linked to an application
        'app_id' => '16638156474000802' # Application ID that has to be linked
}

response = p.link_application_number(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'
});

// Link an application to a number
var params = { 
    'number' : '444444444444', // Number that has to be linked to an application
    'app_id' : '16638156474000802' // Application ID that has to be linked
};

p.link_application_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);
    
    # Link an application to a number
    $params = array(
        'number' => '444444444444', # Number that has to be linked to an application
        'app_id' => '16638156474000802' # Application ID that has to be linked
    );
    $response = $p->link_application_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.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");

        // Link an application to a phone number
        LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
        parameters.put("number","444444444444");
        parameters.put("app_id","16638156474000802");

        try {
            GenericResponse resp = api.linkApplicationNumber(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
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");
            
            // Link an application to a phone number    
            IRestResponse<GenericResponse> resp = plivo.link_application_number(new Dictionary<string,string>()
            {
                {"number","444444444444"}, // Number that has to be linked to an application
                {"app_id","16638156474000802"} // Application ID that has to be linked
            });

            Console.WriteLine(resp.Content);
        }
    }
}

1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"app_id": "16638156474000802"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/

Unlink an Application from a Number

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

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)

# Unlink an application from an number
params = {
    'number' : '444444444444' # Number that has to be unlikned to an application
}

response = p.unlink_application_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)

# Unlink an application from an number
params = {
    'number' => '444444444444' # Number that has to be unlikned to an application
}

response = p.unlink_application_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'
});

// Unlink an application from an number
var params = { 
    'number' : '444444444444' // Number that has to be unlikned to an application
};

p.unlink_application_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);
    
    # Unlink an application from an number
    $params = array(
        'number' => '444444444444' # Number that has to be unlikned to an application
    );
    $response = $p->unlink_application_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");

        // Unlink an application from a phone number
        LinkedHashMap<String, String> param = new LinkedHashMap<String, String>();
        param.put("number","444444444444");
        
        try {
            GenericResponse resp = api.unlinkApplicationNumber(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");
            
            // Unlink an application from a phone number            
            IRestResponse<GenericResponse> response = plivo.unlink_application_number(new Dictionary<string, string>()
            {
                {"number","444444444444"} // Number that has to be unlikned to an application
            });

            Console.WriteLine(response.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}/Number/444444444444/

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.

Rate this page

🥳 Thank you! It means a lot to us!