Phone Number

PhoneNumber objects let you search for and buy a phone number. You can search for local, toll-free, national, mobile, and fixed phone numbers that match a pattern, belong to a certain country, are in a certain region, or are of a certain type. The API lets you buy phone numbers that match your search criteria and add them to your account.

The Phone Number object

Attributes

number string	Phone number that can be purchased.
prefix string	The prefix of the number. This is the area code.
city string	The city of the number. This can be null if the number is national.
country string	The country of the number.
region string	The region (city and country) of the number.
rate_center string	Rate center is available only for US and Canada numbers.
lata string	The local access and transport area of the phone number. This attribute is null for all countries except the US and Canada.
type string	The type of the phone number can be fixed, mobile, or toll-free.
sub_type string	The subtype of the phone number can be fixed, mobile, toll-free, national, or local. local and national numbers are subtypes of fixed numbers.
setup_rate string	The one-time setup fee for the number, in USD.
monthly_rental_rate string	The monthly recurring rental fee for the number, in USD. The monthly fee is billed at the start of each month. If the number is purchased in the middle of a month, the rental fee is prorated and billed at that time.
sms_enabled boolean	Indicates whether the phone number can receive SMS messages.
sms_rate string	The cost (per message) of receiving an SMS message on the number, in USD.
mms_enabled boolean	Indicates whether the phone number can receive MMS messages.
mms_rate string	The cost (per message) of receiving an MMS message on the number, in USD.
voice_enabled boolean	Indicates whether the phone number can receive calls.
voice_rate string	The cost (per minute) of receiving a call on the number, in USD.
restriction string	Indicates the type of verification document required to activate the phone number after its purchase. Verification requirements differ for phone numbers from different countries. Possible values are: city-address: An address proof within the city is required. country-address: An address proof within the phone number’s country is required. terms-and-conditions: No verification document is required when buying the phone number. However, a local address proof should be furnished on request. null: No verification document is required.
restriction_text string	A description of the verification documents required to activate the phone number.
resource_uri string	URI to the phone number resource.
object_typestring	Users can pass object_type as trunk. Mandatory parameter when object_id is present. Object_type will support trunk, phlo, and xml as values in the next release.
object_idstring	Users can pass trunk_id. Mandatory parameter when object_type is present. Object_id will support trunk_id, phlo_id, and xml_id as values in the next release

Response

{
  "number": "14155559186",
  "number_type": "local",
  "object_id": "17248282830499840",
  "object_type": "trunk",
  "prefix": "415",
  "city": "SAN FRANCISCO",
  "country": "UNITED STATES",
  "region": "United States",
  "rate_center": "SNFC CNTRL",
  "lata": 722,
  "type": "fixed",
  "sub_type": "local",
  "setup_rate": "0.00000",
  "monthly_rental_rate": "0.80000",
  "sms_enabled": true,
  "sms_rate": "0.00800",
  "voice_enabled": true,
  "voice_rate": "0.00500",
  "restriction": null,
  "restriction_text": null,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/PhoneNumber/14154009186/",
}

List all rented numbers API

The API gets the details of a phone number that you’ve rented from Plivo or added from your carrier.

API Endpoint

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

Arguments

type string	The type of number. You can filter by local, mobile, fixed, national, or toll-free numbers.
number_startswith string	Only show phone numbers that begin with this pattern.
subaccount string	Returns phone numbers associated with this subaccount.
alias string	Returns phone numbers that exactly match this alias.
services string	Filters phone numbers that provide the selected services. Possible values are: voice: Indicates that phone numbers that can receive calls are to be returned. sms: Indicates that phone numbers that can receive SMS messages are to be returned. mms: Indicates that phone numbers that can receive MMS messages are to be returned. voice,sms: Indicates that phone numbers that can receive both calls and SMS messages are to be returned. voice,sms,mms: Indicates that phone numbers that can receive calls and SMS and MMS messages are to be returned.
limit integer	Denotes the number of results to display per page. The maximum number of results that can be fetched is 20. Defaults to 20.
offset integer	Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about offset-based pagination.
object_typestring	Users can pass object_type as trunk. Mandatory parameter when object_id is present. Object_type will support trunk, phlo, and xml as values in the next release.
object_idstring	Users can pass trunk_id. Mandatory parameter when object_type is present. Object_id will support trunk_id, phlo_id, and xml_id as values in the next release.

Returns

A dictionary with an objects property that contains a list of up to limit account phone numbers. Each tuple in the list is a separate AccountPhoneNumber object. Plivo returns an empty list if there are no phone numbers in the account that match the provided criteria.

Example Request

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
/**
 * Example for Number list
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->numbers->list(
        [
            'object_id' => '33123401372191272',
            'object_type' => 'trunk'
        ]
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}

Was this code helpful

Response

HTTP Status Code: 200

{
  "api_id": "114de006-1c95-11e4-8a4a-123140008edf",
  "meta": {
    "limit": 3,
    "next": "/v1/Account/MA2025RK4E639VJFZAGV/Number/?limit=3&offset=3",
    "offset": 0,
    "previous": null,
    "total_count": 20
  },
  "objects": [{
      "number": "18135401302",
      "object_id": "17248282830499840",
      "object_type": "trunk",
      "alias": null,
      "sub_account": null,
      "added_on": "2021-08-05",
      "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/29986316244302815/",
      "carrier": "Plivo",
      "region": "Florida, UNITED STATES",
      "number_type": "local",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "sms_rate": "0.00000",
      "voice_enabled": true,
      "voice_rate": "0.00850",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/18135401302/"
    },
    {
      "number": "14153661106",

      "alias": "",
      "sub_account": null,
      "added_on": "2022-01-01",
      "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/16632559604105954/",
      "carrier": "Plivo",
      "region": "BELVEDERE, UNITED STATES",
      "number_type": "local",
      "object_id": "17248282830499840",
      "object_type": "trunk",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "sms_rate": "0.00000",
      "voice_enabled": true,
      "voice_rate": "0.00850",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/14153661106/"
    }
  ]
}

Example Request

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)

Was this code helpful

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

Was this code helpful

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);
});

Was this code helpful

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);
    
?>

Was this code helpful

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());            
        }
    }
}

Was this code helpful

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);
        }
    }
}

Was this code helpful

Get an account phone number

Get the details of a phone number that you’ve rented from Plivo or added from your carrier.

API Endpoint

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

Arguments

No arguments need to be passed.

Returns

Returns an AccountPhoneNumber object.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#
# Example for Number Get
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

begin
  response = api.numbers.get(
    '17609915566'
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for Number get

var plivo = require('plivo');

(function main() {
    'use strict';
    
   // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
    var client = new plivo.Client("<auth_id>","<auth_token>");
    client.numbers.get(
        "17609915566", // number
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
 * Example for Number get
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->numbers->get(
        '17609915566'
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package com.plivo.api.samples.number;

import java.io.IOException;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.number.Number;
import com.plivo.api.models.number.Number;

/**
* Example for Number get
*/
class NumberGet {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            Number response = Number.getter("17609915566")
                .get();

            System.out.println(response);
        } catch (PlivoRestException | IOException e) {
            e.printStackTrace();
        }
    }
}

Was this code helpful

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
/**
 * Example for Number Get
 */
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            try
            {
                var response = api.Number.Get(
                    number:"17609915566"
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for Number get
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Numbers.Get(
		"17609915566",
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

Response

HTTP Status Code: 200

{
  "added_on": "2023-02-14",
  "alias": null,
  "api_id": "88625e5e-1c92-11e4-80aa-12313f048015",
  "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/29986316244302815/",
  "carrier": "Plivo",
  "monthly_rental_rate": "0.80000",
  "number": "17605551234",
  "number_type": "local",
  "object_id": "17248282830499840",
  "object_type": "trunk",
  "region": "California, UNITED STATES",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/17609915566/",
  "sms_enabled": true,
  "sms_rate": "0.00000",
  "sub_account": null,
  "voice_enabled": true,
  "voice_rate": "0.00850"
}

Example Request

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)

Was this code helpful

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

Was this code helpful

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);
});

Was this code helpful

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);
    
?>

Was this code helpful

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());            
        }
    }
}

Was this code helpful

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
        }
    }
}

Was this code helpful

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
    // Example for Number get
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Numbers.Get(
		"17609915566",
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

Update phone number

Change the application and subaccount associated with a specified phone number from your account.

API Endpoint

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

Arguments

app_id stringrequired — conditional	The application to be assigned to the phone number. If not specified, the application selected as the default_number_app of the account is assigned. For more information, refer to the default_number_app argument in application and the app_id attribute in application object. You may use either app_id or object_id but not both.
subaccount string	The auth_id of the subaccount to which this number should be added. This can be performed only by the main account.
alias string	An alias assigned to the phone number.
object_typestring	Users can pass object_type as trunk. Mandatory parameter when object_id is present. Object_type will support trunk, phlo, and xml as values in the next release.
object_idstring	Users can pass trunk_id. Mandatory parameter when object_type is present. Object_id will support trunk_id, phlo_id, and xml_id as values in the next release.
message_methodstringrequired — conditional	Allowed values: GET, POST Allowed for voice- and SMS-enabled numbers. Required if message_url is passed.
message_urlstringrequired — conditional	Message URL of length not greater than 255 characters. Allowed only for voice- and SMS-enabled numbers. Required if message_method is passed.

app_id cannot be updated when object_type is set as trunk and object id is provided.

Example Request

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?php
/**
 * Example for Number update
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->numbers->update(
        '12025551111',
        [
        'object_id' => '33123401372191272',
        'object_type' => 'trunk',
        'message_method' => 'POST',
        'message_url' => 'https://www.plivo.com']
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}

Was this code helpful

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/12025551111/

Was this code helpful

Response

HTTP Status Code: 202

{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}

Example Request

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)

Was this code helpful

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)

Was this code helpful

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);
});

Was this code helpful

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);
    
?>

Was this code helpful

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());
        }
    }
}

Was this code helpful

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);
        }
    }
}

Was this code helpful

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/

Was this code helpful

Buy a phone number

This API lets you buy a phone number and add it to your account. If the number is for a country that requires address and identity verification, you must provide verification documents before Plivo can activate the phone number.

API Endpoint

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

Arguments

app_id string	The application to be assigned to the phone number. If not specified, the application selected as the default_number_app of the account is assigned. For more information, refer to the default_number_app argument in application and the app_id attribute in application object. You may use either app_id or object_id but not both.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#
# Example for PhoneNumber Create
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

begin
  response = api.phone_numbers.buy(
    '441273257545',
    'app id to link with'
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for PhoneNumber create

var plivo = require('plivo');

(function main() {
    'use strict';
    
   // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
    var client = new plivo.Client("<auth_id>","<auth_token>");
    client.numbers.buy(
        "441273257545", // number
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
 * Example for PhoneNumber create
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->phonenumbers->buy(
        '441273257545'
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package com.plivo.api.samples.phonenumber;

import java.io.IOException;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.number.PhoneNumber;
import com.plivo.api.models.number.PhoneNumberCreateResponse;

/**
* Example for PhoneNumber create
*/
class PhoneNumberCreate {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            PhoneNumberCreateResponse response = PhoneNumber.creator("441273257545")
                .create();

            System.out.println(response);
        } catch (PlivoRestException | IOException e) {
            e.printStackTrace();
        }
    }
}

Was this code helpful

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
/**
 * Example for PhoneNumber Create
 */
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            try
            {
                var response = api.PhoneNumber.Buy(
                    number:"441273257545"
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

Was this code helpful

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
// Example for PhoneNumber create
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.PhoneNumbers.Create(
		"123",
		plivo.PhoneNumberCreateParams{},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

Response

HTTP Status Code: 201

{
    "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
    "message": "created",
    "numbers": [
        {
            "number": "14155559186",
            "status": "Success"
        }
    ],
    "status": "fulfilled"
}

If the number is for a country with verification requirements, Plivo sends an email message to the registered email address for the account that describes the requirements, and returns this response.

{
    "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
    "message": "created",
    "numbers": [
        {
            "number": "4969365065273",
            "status": "pending"
        }
    ],
    "status": "fulfilled"
}

Example Request

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)

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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

Was this code helpful

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);
});

Was this code helpful

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);
    
?>

Was this code helpful

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());            
        }
    }
}

Was this code helpful

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);
        }
    }
}

Was this code helpful

Search phone numbers

Returns a list of phone numbers that are available for purchase. You can search for toll-free, mobile, local, national, and fixed phone numbers. The API lets you filter phone numbers based on several criteria.

API Endpoint

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

Arguments

country_iso Requiredstring	The ISO 3166 alpha-2 country code of the country. To see what number types we support in each country, visit our voice and SMS coverage pages.
type string	Filters by the type of the phone number. Allowed values: toll-free, local, mobile, national, fixed.
pattern string	A pattern to match the phone number with. Phone numbers starting with (numeric country code + pattern) are filtered in. Allowed values are A-Z, 0-9, *, and ?. For example, to search for phone numbers in the US starting with a 415 prefix, specify Pattern = 415. Filtered results will be in the form "1415nnnnnnn"
npanxx six-digit integer	Filters local US and CA numbers based on the provided six-digit prefix. The filter is applicable only if the country is US or CA. For example, to search for 1 (737) 977-nnnn, set "npanxx" = 737 977. To be used in combination with the local_calling_area filter.
local_calling_area boolean	If set to true, expands the search results to include phone numbers that are local to the searched `npanxx`. The filter is only applicable if `npanxx` is provided. Read more about local calling. Defaults to false.
Note: If `local_calling_area` is set to true, phone numbers in the search results might not match the searched `npanxx`. All phone numbers in the search results will be in the local calling radius of the searched `npanxx`.
region string min. length is 2	Filters by the exact name of a region: for instance, region=Frankfurt. This filter is applicable only when the type is fixed. If no type is provided, type is assumed to be fixed.
services string	Filters phone numbers that provide the selected services. Allowed values are: voice: Indicates that phone numbers that can receive calls are to be returned. sms: Indicates that phone numbers that can receive SMS messages are to be returned. mms: Indicates that phone numbers that can receive MMS messages are to be returned. voice,sms: Indicates that phone numbers that can receive both calls and SMS messages are to be returned. voice,sms,mms: Indicates that phone numbers that can receive calls and SMS and MMS messages are to be returned.
city string	Filters based on the city name. This filter is applicable only when the type is local.
lata	Filters by LATA. This filter is applicable only for US and Canada.
rate_center	Filters by rate center. This filter is applicable only for US and Canada.
limit default is 20	A limit on the number of phone numbers to be returned. `limit` can range between 1 and 20, and the default is 20.
offset integer	Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about offset-based pagination.

Returns

A dictionary with an objects property that contains a list of up to limit phone numbers. Each tuple in the list is a separate PhoneNumber object. An empty list is returned if there are no phone numbers matching the provided criteria.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#
# Example for PhoneNumber List
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

begin
  response = api.phone_numbers.search(
    'GB',
    limit: 5
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for PhoneNumber list

var plivo = require('plivo');

(function main() {
    'use strict';
    
   // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
    var client = new plivo.Client("<auth_id>","<auth_token>");
    client.numbers.search(
        "GB", // country iso
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
/**
 * Example for PhoneNumber list
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->phonenumbers->list(
        'GB'
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package com.plivo.api.samples.phonenumber;

import java.io.IOException;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.number.PhoneNumber;
import com.plivo.api.models.base.ListResponse;

/**
* Example for PhoneNumber list
*/
class PhoneNumberList {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            ListResponse<PhoneNumber> response = PhoneNumber.lister("GB")
                .list();

            System.out.println(response);
        } catch (PlivoRestException | IOException e) {
            e.printStackTrace();
        }
    }
}

Was this code helpful

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
/**
 * Example for PhoneNumber List
 */
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            try
            {
                var response = api.PhoneNumber.List(
                    countryIso:"GB"
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

Was this code helpful

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
// Example for PhoneNumber list
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.PhoneNumbers.List(
		plivo.PhoneNumberListParams{
			CountryISO: "GB",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

Response

HTTP Status Code: 200

{
  "api_id": "859428b0-1c88-11e4-a2d1-22000ac5040c",
  "error" : "",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 9
  },
  "objects": [
    {
      "number": "14154009186",
      "prefix": "415",
      "city": "SAN FRANCISCO",
      "country": "UNITED STATES",
      "region": "United States",
      "rate_center": "SNFC CNTRL",
      "lata": 722,
      "type": "fixed",
      "sub_type": "local",
      "setup_rate": "0.00000",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "sms_rate": "0.00800",
      "voice_enabled": true,
      "voice_rate": "0.00500",
      "restriction": null,
      "restriction_text": null,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/PhoneNumber/14154009186/",
    },
    {
      "number": "14154009187",
      "prefix": "415",
      "city": "SAN FRANCISCO",
      "country": "UNITED STATES",
      "region": "United States",
      "rate_center": "SNFC CNTRL",
      "lata": 722,
      "type": "fixed",
      "sub_type": "local",
      "setup_rate": "0.00000",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "sms_rate": "0.00800",
      "voice_enabled": true,
      "voice_rate": "0.00500",
      "restriction": null,
      "restriction_text": null,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/PhoneNumber/14154009187/",
    }
  ]
}

Example Request

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)

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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

Was this code helpful

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);
});

Was this code helpful

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);  
?>

Was this code helpful

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());
        } 
    }
}

Was this code helpful

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);
        }
    }
}

Was this code helpful