Latest Legacy

Overview

All Plivo APIs use HTTP verbs and standard HTTP status codes to make it easy for you to integrate communications into your code. To secure requests to our servers, we serve our APIs over HTTPS.

Note: The current version of the APIs is v1, and the server SDKs are versioned as latest and legacy.

API Endpoint

POST https://api.plivo.com/{version}/

API Request

Plivo exposes a list of REST API calls to perform various actions. You can use these API calls in combination with XML code to create voice and SMS applications.

POST https://api.plivo.com/v1/

Authentication

All requests to Plivo APIs are authenticated with BasicAuth using your Auth ID and Auth Token, which you can find on the overview page of the Plivo console.

Example Request

1
2
3
4
5
6
7
import plivo

proxies = {
    'http': 'https://username:password@proxyurl:proxyport',
    'https': 'https://username:password@proxyurl:proxyport'
    }
client = plivo.RestClient('<auth_id>', '<auth_token>', proxies=proxies,timeout=5)

Was this code helpful

1
2
3
4
5
6
7
8
9
10
require 'rubygems'
require 'plivo'

proxy = {
	proxy_host: "https://proxyurl",
	proxy_port: "proxyport",
	proxy_user: "username",
	proxy_pass: "password"
}
api = RestClient.new("<auth_id>", "<auth_token>", proxy, timeout=5)

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
var plivo = require('plivo');
let options = {
	'timeout': 5000, //ms
	'host': 'https://proxyurl',
	'port': 'proxyport',
	auth: {
		username: 'my-user',
		password: 'my-password'
	}
}

var client = new plivo.Client("<auth_id>", "<auth_token>", options);

Was this code helpful

1
2
3
4
5
6
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>", "<auth_token>", "<https://proxyurl>", "<proxyport>", "<username>", "<password>");
$client->client->setTimeout(5)

Was this code helpful

1
2
3
4
5
6
7
8
9
package com.plivo.api.samples.application;

import com.plivo.api.Plivo;

class AutheExample {
  public static void main(String [] args) {
    Plivo.init();
  }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
using System;
using System.Collections.Generic;
using Plivo;

namespace PlivoExamples {
  internal class Program {
    public static void Main(string[] args) {
      var api = new PlivoApi(
        "<auth_id>", "<auth_token>",
        "<https://proxyurl>", "<proxyport>", "<username>", "<password>");
      api.Client.SetTimeout(10);
    }
  }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
package main

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

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		panic(err)
	}
}

Was this code helpful

Content-Type

Plivo accepts input only of the type application/json.

All POST request arguments must be passed as json with the Content-Type set as application/json.

All GET and DELETE request arguments must be passed in the query string.

Timeouts and Proxies

Plivo’s server SDKs let you specify timeouts and proxy settings to be used when making API requests. Select the programming language of your choice and view the latest version to see how to specify these settings.

Pagination

Plivo uses offset-based pagination to list resources.

For instance, if your search request has a result of 100 objects with limit = 10 and offset = 5, then Plivo will return objects with indices 51 through 60.

Parameters used for pagination

limit integer	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	A pagination cursor to denote the number of objects by which the results should be offset.

Asynchronous Request

All requests to Plivo APIs can be made asynchronous by adding the parameters listed below. When you make an asynchronous API call, Plivo returns a generic response with the api_id, and sends the API responses to the specified callback URL.

Arguments

callback_url	The URL to be notified by the API response.
callback_method	The method used to notify the callback_url. Defaults to POST.

Response

{
"message": "async api spawned",
"api_id": "63f0761a-e0ed-11e1-8ea7-12313924e3a6"
}

API responses

All Plivo API endpoints return a response in JSON format. Plivo sets an api_id in each response to uniquely identify your request. The API returns one of these HTTP status codes depending on whether the call succeeds or fails.

200	Request has been executed
201	Resource created
202	Resource changed
204	Resource deleted
206	Partial success
400	A parameter is missing or is invalid
401	Authentication failed
404	Resource cannot be found
405	HTTP method not allowed
429	Too many requests, rate limited
500	Server error

Response Examples

Response Attributes

api_idstring	Identifies the request.
errorstring	Indicates there’s an error and provides information regarding the error.
messagestring	Provides information regarding the request.

Response

Success

{
  "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
  "message": "call fired",
  "request_uuid": "75b26856-8638-11e0-802c-6d99d509954e"
}

Error

{
  "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
  "error": "answer_url parameter is missing",
  "request_uuid": "56hf4856-8638-11e0-802c-65j6gd39954e"
}

Account Phone Number

You create an account phone number object when you rent a phone number from Plivo or add a phone number from your incoming carrier. With this API you can list all account phone numbers, retrieve details, and unrent a phone number.

API Endpoint

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

The AccountPhoneNumber object

Attributes

number string	The phone number.
alias string	Alias for the phone number.
subaccount string	The subaccount with which the phone number is associated. If phone number belongs to the main account, this value will be null.
added_on string	The date on which the number was rented to the account. Format: YYYY-MM-DD
application string	The application linked to the number.
carrier string	The carrier linked to the phone number. This can either be a Plivo carrier or an incoming carrier that you’ve added.
region string	The region (city and country) of the phone number.
number_type string	The type of the number. Can be local, fixed, tollfree, mobile, or national.
monthly_rental_rate string	The monthly rental fee for the phone number, in USD.
renewal_date string	The date on which the number rental will be renewed and you will be charged the monthly rental rate. Format: YYYY-MM-DD.
sms_enabled boolean	Indicates whether the phone number can receive SMS.
sms_rate string	The cost (per message) of receiving SMS on the number, in USD.
mms_enabled boolean	Indicates whether the phone number can receive MMS.
mms_rate string	The cost (per message) of receiving MMS 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.
cnam_lookup string	Indicates whether CNAM lookup service is enabled or disabled on US local and toll-free numbers. Can be enabled or disabled. For other numbers, this value is null.
cnamstring	The caller ID name that call receivers will see when you call them from this number.
cnam_registration_statusstring	The status of cnam registration. Possible values are: IN_PROGRESS: cnam registration is in progress REGISTERED FAILED: The latest registration attempt failed. The active caller ID name is shown under the 'cnam' key.
resource_uri string	URI to the account phone number resource.
tendlc_registration_status string	The 10DLC registration status of US local numbers. Can be UNREGISTERED, PROCESSING, COMPLETED. This value is null if a number is not a US local number that is SMS-enabled.
tendlc_campaign_id string	The specific 10DLC campaign ID that the phone number is linked to. If a phone number Is not linked to any 10DLC campaign, this value is null.
toll_free_sms_verification string	The SMS verification status for US/Canada toll-free numbers that are SMS-enabled. Can be UNVERIFIED, PENDING_VERIFICATION, VERIFIED. For other numbers types, this value is null.

Response

{
  "number": "17609915566",
  "alias": null,
  "sub_account": null,
  "added_on": "2023-02-14",
  "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/29986316244302815/",
  "carrier": "Plivo",
  "region": "California, UNITED STATES",
  "number_type": "local",
  "monthly_rental_rate": "0.80000",
  "renewal_date": "2023-05-10",
  "sms_enabled": true,
  "sms_rate": "0.00000",
  "voice_enabled": true,
  "voice_rate": "0.00850",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/17609915566/",
  "tendlc_campaign_Id":"2FA_campaign",
  "tendlc_registration_status":"COMPLETED",
  "toll_free_sms_verification":null
}

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",
  "renewal_date": "2023-05-10",
  "number": "17609915566",
  "number_type": "local",
  "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

List account phone numbers

Returns a list of phone numbers that you’ve rented from Plivo or or added from your carrier.

API Endpoint

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

Arguments

type string	The type of number. You can filter by local, mobile, fixed, national, or tollfree 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.
cnam_lookup string	Filters US phone numbers by their CNAM lookup configuration status. Valid values are enabled and disabled.
renewal_date string	Filters phone numbers by their renewal date. Format: YYYY-MM-DD. The filter can be used in these five forms: renewal_date: To get all numbers renewed on 2023-05-10, use renewal_date=2023-05-10. renewal_date__gt: gt stands for greater than. To get all numbers renewed after 2023-05-10, use renewal_date__gt=2023-05-10. renewal_date__gte: gte stands for greater than or equal to. To get all numbers renewed on or after 2023-05-10, use renewal_date__gte=2023-05-10. renewal_date__lt: lt stands for less than. To get all numbers renewed before 2023-05-10, use renewal_date__lt=2023-05-10. renewal_date__lte: lte stands for less than or equal to. To get all numbers renewed on or before 2023-05-10, use renewal_date__lte=2023-05-10. Note: You can combine these filters to get numbers that are renewed in a particular date range.
tendlc_registration_status string	The 10DLC registration status of US local numbers. Valid values: unregistered: returns a list of numbers that are not linked to a campaign. in_progress: returns a list of numbers that are in the process of being linked to campaigns. registered: returns a list of numbers that are linked to campaigns.
tendlc_campaign_id string	10DLC campaign ID that the phone number is linked to. You can filter US local numbers that are linked to a specific campaign.
toll_free_sms_verification string	SMS verification status for SMS-enabled US/Canada toll-free numbers. Valid values: unverified: returns a list of SMS-enabled US/CA toll-free numbers that are not verified. pending_verification: returns a list of SMS-enabled US/CA toll-free numbers that are pending verification. verified: returns a list of SMS-enabled US/CA toll-free numbers that are verified for enhanced outbound SMS limits.
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.

Example Request

1
2
3
4
5
6
7
8
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.list(
    limit=5,
    offset=0,
    type='fixed', )
print(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
#
# Example for Number List
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

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

begin
  response = api.numbers.list(
    limit: 5,
    offset: 0
  )
  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
18
19
20
// Example for Number 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.list(
        {
            limit: 5,
            offset: 0,
        },
    ).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
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(
        [
        	'limit' => 4,
        	'offset' => 4
        ]
    );
    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
25
26
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.base.ListResponse;

/**
* Example for Number list
*/
class NumberList {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            ListResponse<Number> response = Number.lister()
                .limit(5)
                .offset(0)
                .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
30
/**
 * Example for Number 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.Number.List(
                    limit:5,
                    offset:0
                );
                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
27
// Example for Number 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.Numbers.List(
		plivo.NumberListParams{
			Limit:  5,
			Offset: 0,
		},
	)
	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": "114de006-1c95-11e4-8a4a-123140008edf",
  "meta": {
    "limit": 2,
    "next": "/v1/Account/MA2025RK4E639VJFZAGV/Number/?limit=3&offset=3",
    "offset": 0,
    "previous": null,
    "total_count": 20
  },
  "objects": [{
      "number": "18135401302",
      "alias": null,
      "sub_account": null,
      "added_on": "2022-08-05",
      "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/29986316244302815/",
      "carrier": "Plivo",
      "region": "Florida, UNITED STATES",
      "number_type": "local",
      "monthly_rental_rate": "0.80000",
      "renewal_date": "2023-05-10",
      "sms_enabled": true,
      "sms_rate": "0.00000",
      "voice_enabled": true,
      "voice_rate": "0.00850",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/18135401302/",
      "tendlc_campaign_Id":"2FA_campaign",
      "tendlc_registration_status":"COMPLETED"
      "toll_free_sms_verification":null
    },
    {
      "number": "14153661106",
      "alias": "",
      "sub_account": null,
      "added_on": "2023-01-01",
      "application": "/v1/Account/MA2025RK4E639VJFZAGV/Application/16632559604105954/",
      "carrier": "Plivo",
      "region": "BELVEDERE, UNITED STATES",
      "number_type": "local",
      "monthly_rental_rate": "0.80000",
      "renewal_date": "2023-05-10",
      "sms_enabled": true,
      "sms_rate": "0.00000",
      "voice_enabled": true,
      "voice_rate": "0.00850",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Number/14153661106/",
      "tendlc_campaign_Id":"Product_Marketing",
      "tendlc_registration_status":"COMPLETED",
      "toll_free_sms_verification":null
    }
  ]
}

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

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 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.Numbers.List(
		plivo.NumberListParams{
			Limit:  5,
			Offset: 0,
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

Update an account phone number

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

API Endpoint

POST https://api.plivo.com/v1/Account/{auth_id}/Number/{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. Zentrunk customers can pass the inbound trunk_id as the app_id to map the number to the inbound trunk.
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.
cnam_lookup string	Updates CNAM lookup configuration for a number. Applicable only for US local and toll-free numbers. Valid values are enabled and disabled. For other numbers, this value is null.
cnam (optional)string	The caller ID name you want call receivers to see when they receive calls from this number
cnam_callback_url (optional)string	Plivo invokes this URL when there is an update to the cnam registration request
cnam_callback_method (optional)string	The HTTP verb that should be used to invoke the URL configured as cnam_callback_url Allowed values: GET, POST Defaults to POST.

List of events and parameters sent to the cnam_callback_url

apiIdstring	Unique ID of the callback response
cnamUpdateStatusstring	Status of the request to update CNAM Possible values: “success”, “failed”
requestedCnamstring	The caller ID (CNAM) that was requested
Numberstring	The phone number for which CNAM was requested

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.update(
    number='12025551111',
    alias='Updated Alias', )
print(response)

# Or you could use the Number object directly to update the details
client = plivo.RestClient('<auth_id>','<auth_token>')
number = client.numbers.get(
    number='12025551111', )
response = number.update(
    alias='Updated Alias', )
print(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
#
# Example for Number Update
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

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

begin
  response = api.numbers.update(
    '12025551111',
    alias: 'Updated Alias'
  )
  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
18
19
20
// Example for Number update

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.update(
        "12025551111",
        {
            alias: "Updated Alias",
        },
    ).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
19
<?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',
        ['alias' => 'Updated Alias']
    );
    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
25
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.NumberUpdateResponse;

/**
* Example for Number update
*/
class NumberUpdate {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            NumberUpdateResponse response = Number.updater("12025551111")
                .alias("Updated Alias")
                .update();

            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
30
/**
 * Example for Number Update
 */
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.Update(
                    alias:"Updated Alias",
                    number:"12025551111"
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

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

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
// Example for Number update
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.Update(
		"12025551111",
		plivo.NumberUpdateParams{
			Alias: "Updated Alias",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

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

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 update
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.Update(
		"12025551111",
		plivo.NumberUpdateParams{
			Alias: "Updated Alias",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Was this code helpful

Unrent a number

Unrent the phone number from your account. This operation cannot be undone.

API Endpoint

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

Arguments

No arguments need to be passed.

Example Request

1
2
3
4
5
6
7
8
9
10
11
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.delete(
    number='12025551111', )
print(response)

# Or you could use the number object directly to delete it
number = client.numbers.get('12025551111')
response = number.delete()
print(response)

Was this code helpful

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

include Plivo
include Plivo::Exceptions

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

begin
  response = api.numbers.delete(
    '12025551111'
  )
  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 delete

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.unrent(
        "12025551111",
    ).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 delete
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->numbers->delete(
        '12025551111'
    );
    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
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;

/**
* Example for Number delete
*/
class NumberDelete {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            Number.deleter("12025551111")
                .delete();

            System.out.println("Deleted successfully.");
        } 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 Delete
 */
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.Delete(
                    number:"12025551111"
                );
                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 delete
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
	}
	err = client.Numbers.Delete(
		"12025551111",
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Println("Deleted successfully.")
}

Was this code helpful

Response

HTTP Status Code: 204

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)

# Unrent a number
params = {
    'number' : '1111111111' # Number that has to be unrented
}

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

# Unrent a number
params = {
        'number' => '1111111111' # Number that has to be unrented
}

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

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

Was this code helpful

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

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

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

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 delete
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
	}
	err = client.Numbers.Delete(
		"12025551111",
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Println("Deleted successfully.")
}

Was this code helpful

Add a number from your own carrier

Adds a phone number from your own carrier to your account.

API Endpoint

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

Arguments

numbers Requiredstring	A comma-separated list of numbers to be added to the account. These numbers should be configured to point to the SIP address <phone_number\>@sbc.plivo.com. For instance, the phone number 18554675486 should point to 18554675486@sbc.plivo.com.
carrier Requiredstring	The ID of the IncomingCarrier that the number is associated with. For more information, see IncomingCarrier.
region Requiredstring	A free-text field you can use to describe the region of this phone number.
number_type string	The type of the phone number. You can use number_type to differentiate between mobile, local, and toll-free numbers in the account. Defaults to local.
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 app_id attribute in application object.
subaccount string	The auth_id of the subaccount to which this number should be added. You can map a phone number to a subaccount only from the main account.

Response

HTTP Status Code: 202

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

PhoneNumber

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 PhoneNumber 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 tollfree.
sub_type string	The subtype of the phone number can be fixed, mobile, tollfree, 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.

Response

{
  "number": "14155559186",
  "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/",
}

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 are tollfree, local, mobile, national, and 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, "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.
compliance_requirementstring	References the Compliance requirements associated with the phone number. {Null} denotes that the phone number does not have any regulatory requirements.

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

Buy a Phone Number

Buys a phone number and adds it to your account. If the number is for a country that requires address and identity verification, you must provide verification documents before we 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 under Application and `app_id` attribute in the Application object.
cnam_lookup string	Enable or disable CNAM lookup on the number being rented. Applicable only for US local and toll-free numbers. Valid values are enabled and disabled. For other numbers, this value is null.

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": "14154009186",
            "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

Incoming carrier

Use this API if you own phone numbers from a carrier and want to route incoming calls on that carrier’s numbers through Plivo.

API Endpoint

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

The IncomingCarrier object

Attributes

carrier_id string	The ID of the incoming carrier. Plivo assigns a unique identifier to each carrier instance that we create on our platform.
ip_set string	A comma-separated list of IP addresses associated with the incoming carrier.
name string	Name of the incoming carrier.
resource_uri string	The URI for the incoming carrier resource.
sms boolean	Indicates whether the incoming carrier supports handling SMS messages.
voice boolean	Indicates whether the incoming carrier supports handling voice calls.

Response

{
  "carrier_id": "19381640842535",
  "ip_set": "10.20.10.20,10.10.10.10,10.20.10.30",
  "name": "Custom carrier 1",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/IncomingCarrier/19381640842535/",
  "sms": false,
  "voice": true
}

Create an incoming carrier

This API lets you add a new incoming carrier to your Plivo account.

API Endpoint

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

Arguments

name Required	The name of the carrier being added. You can use any name. Allowed Values: Alphabets (upper case and lower case) Numbers (0-9). Only 2 special characters, i.e. "-" (hyphen) and "_" (underscore)
ip_set Required	Comma-separated list of IP addresses from which calls belonging to the carrier will reach Plivo. Plivo checks this list to determine whether to allow incoming calls into Plivo’s servers, and will not accept calls that come from IP addresses not on this list.

Response

HTTP Status Code: 201

{
    "api_id": "65368fb6-5060-11e4-8a4a-123140008edf",
    "carrier_id": "13455781930894",
    "message": "created"
}

Retrieve an incoming carrier

This API returns the details of an incoming carrier.

API Endpoint

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

Arguments

No arguments need to be passed.

Returns

Returns an IncomingCarrier object.

Response

HTTP Status Code: 200

{
    "api_id": "18c3881e-5060-11e4-8a4a-123140008edf",
    "carrier_id": "12209049768983",
    "ip_set": "172.168.1.4",
    "name": "Bermuda",
    "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/IncomingCarrier/12209049768983/",
    "sms": false,
    "voice": true
}

List all incoming carriers

This API lists all incoming carrier registered with your account.

API Endpoint

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

Arguments

name string	Allows filtering by name. The filter term can be either the exact name of the carrier or a phrase contained within the name the carrier (includes the “starts with” filter).
limit integer	Denotes the number of results to display per page. The maximum number of results that can be fetched is 20.
offset integer	Denotes the number of value items by which the results should be offset.

Response

HTTP Status Code: 200

{
  "meta": {
    "previous": null,
    "total_count": 1,
    "offset": 0,
    "limit": 20,
    "next": null
  },
  "api_id": "a90cbe28-58d7-11e1-86da-adf28403fe48",
  "objects": [
    {
      "carrier_id": "19381640842535",
      "ip_set": "10.20.10.20,10.10.10.10,10.20.10.30",
      "name": "Custom carrier 1",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/IncomingCarrier/19381640842535/",
      "sms": false,
      "voice": true
      }
  ]
}

Update an incoming carrier

This API lets you modify an existing incoming carrier set up on your account.

API Endpoint

POST https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/

Arguments

name Requiredstring	The name of the carrier. You can use any name. Allowed Values: Alphabets (upper case and lower case) Numbers (0-9). Only 2 special characters, i.e. "-" (hyphen) and "_" (underscore)
ip_set Requiredstring	Comma-separated list of IP addresses from which calls belonging to the carrier will reach Plivo. Plivo checks this list to determine whether to allow incoming calls into Plivo’s servers, and will not accept calls that come from IP addresses not on this list. The complete set of IP addresses is replaced when you call this API.

Response

HTTP Status Code: 202

{
"api_id": "7127cccc-5060-11e4-80aa-12313f048015",
"message": "changed"
}

Delete an incoming carrier

This API lets you remove an incoming carrier from your account.

When you remove a carrier, all numbers associated with the carrier are deleted.

API Endpoint

DELETE https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/

Arguments

No arguments need to be passed.

Response

HTTP Status Code: 204

Rate this page

🥳 Thank you! It means a lot to us!