Phone Number API

The following 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 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.

Search for New Numbers

This API call enables you search for fixed, mobile and tollfree numbers available on Plivo. Searches can be performed based on any combination of the two-letter country code, number pattern, number type and region. It returns a list of numbers matching the search criteria which 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

Sample Response

(200, {
       u'meta': {
            u'previous': None, 
            u'total_count': 100, 
            u'offset': 0, 
            u'limit': 20, 
            u'next': u'/v1/Account/XXXXXXXXXXXX/PhoneNumber/?limit=20&country_iso=US&pattern=210&region=Texas&offset=20&type=local'
        }, u'objects': [
            {
                u'restriction': None, 
                u'rate_center': u'SANANTONIO', 
                u'voice_enabled': True, 
                u'country': u'UNITED STATES', 
                u'region': u'Texas, UNITED STATES', 
                u'restriction_text': None, 
                u'prefix': u'210', 
                u'number': u'12109206499', 
                u'monthly_rental_rate': u'0.80000', 
                u'voice_rate': u'0.00850', 
                u'lata': 566, 
                u'setup_rate': u'0.00000', 
                u'sms_rate': u'0.00000', 
                u'type': u'fixed', 
                u'sms_enabled': True, 
                u'resource_uri': u'/v1/Account/XXXXXXXXXXXX/PhoneNumber/12109206499/'
            }, {
                u'restriction': None, 
                u'rate_center': u'SANANTONIO', 
                u'voice_enabled': True, 
                u'country': u'UNITED STATES', 
                u'region': u'Texas, UNITED STATES', 
                u'restriction_text': None, 
                u'prefix': u'210', 
                u'number': u'12109206500', 
                u'monthly_rental_rate': u'0.80000', 
                u'voice_rate': u'0.00850', 
                u'lata': 566, 
                u'setup_rate': u'0.00000', 
                u'sms_rate': u'0.00000', 
                u'type': u'fixed', 
                u'sms_enabled': True, 
                u'resource_uri': u'/v1/Account/XXXXXXXXXXXX/PhoneNumber/12109206500/'
            }
        ], u'api_id': u'd8692ccc-b66e-11e4-ac1f-22000ac51de6'
    }
)

Rent a number

The number retrieved from the search above can then be used as input to rent the number under 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/

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/'
    }
)

Next Step

Learn how to query the Pricing API.

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