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
.
POST
https://api.plivo.com/{version}/
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/
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.
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
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.
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.
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.
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. |
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.
callback_url | The URL to be notified by the API response. |
callback_method | The method used to notify the callback_url. Defaults to POST. |
{
"message": "async api spawned",
"api_id": "63f0761a-e0ed-11e1-8ea7-12313924e3a6"
}
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 |
api_idstring | Identifies the request. |
errorstring | Indicates there’s an error and provides information regarding the error. |
messagestring | Provides information regarding the request. |
{
"api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"message": "call fired",
"request_uuid": "75b26856-8638-11e0-802c-6d99d509954e"
}
{
"api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"error": "answer_url parameter is missing",
"request_uuid": "56hf4856-8638-11e0-802c-65j6gd39954e"
}
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.
BaseURI
https://api.plivo.com/v1/Account/{auth_id}/Number/
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:
|
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. |
{
"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 the details of a phone number that you’ve rented from Plivo or added from your carrier.
GET
https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/
Returns an AccountPhoneNumber
object.
1
2
3
4
5
6
import plivo
client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.get(
number='1314315XXXX', )
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 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
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Number/444444444444/
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
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"
}
Returns a list of phone numbers that you’ve rented from Plivo or or added from your carrier.
GET
https://api.plivo.com/v1/Account/{auth_id}/Number/
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:
|
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:
Note:
|
tendlc_registration_status string | The 10DLC registration status of US local numbers. Valid values:
|
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:
|
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. |
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
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Number/
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
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
}
]
}
Change the application and subaccount associated with the specified phone number from your account.
POST
https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/
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. |
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 |
apiIdstring | Unique ID of the callback response |
cnamUpdateStatusstring | Status of the request to update CNAM Possible values: |
requestedCnamstring | The caller ID (CNAM) that was requested |
Numberstring | The phone number for which CNAM was requested |
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
HTTP Status Code: 202
{
"message": "changed",
"api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}
Unrent the phone number from your account. This operation cannot be undone.
DELETE
https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/
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
curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
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
// 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
HTTP Status Code: 204
Adds a phone number from your own carrier to your account.
POST
https://api.plivo.com/v1/Account/{auth_id}/Number/
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. |
HTTP Status Code: 202
{
"message": "changed",
"api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}
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.
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:
|
restriction_text string | A description of the verification documents required to activate the phone number. |
resource_uri string | URI to the phone number resource. |
{
"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/",
}
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.
GET
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/
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 The filter is only applicable if 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:
|
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. |
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. |
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.
1
2
3
4
5
import plivo
client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.search(country_iso='GB')
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 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
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/?country_iso=US&type=local&pattern=210&region=Texas
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
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/",
}
]
}
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.
POST
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/{number}/
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 |
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. |
1
2
3
4
5
import plivo
client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.buy(number='441273257545')
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 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
curl -X POST -i --user AUTH_ID:AUTH_TOKEN
-H "Content-Type: application/json"
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/444444444444/
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
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"
}
Use this API if you own phone numbers from a carrier and want to route incoming calls on that carrier’s numbers through Plivo.
BaseURI
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/
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. |
{
"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
}
This API lets you add a new incoming carrier to your Plivo account.
POST
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/
name Required |
The name of the carrier being added. You can use any name. |
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. |
HTTP Status Code: 201
{
"api_id": "65368fb6-5060-11e4-8a4a-123140008edf",
"carrier_id": "13455781930894",
"message": "created"
}
This API returns the details of an incoming carrier.
GET
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/
Returns an IncomingCarrier
object.
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
}
This API lists all incoming carrier registered with your account.
GET
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/
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. |
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
}
]
}
This API lets you modify an existing incoming carrier set up on your account.
POST
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/
name Requiredstring |
The name of the carrier. You can use any name. |
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. |
HTTP Status Code: 202
{
"api_id": "7127cccc-5060-11e4-80aa-12313f048015",
"message": "changed"
}
This API lets you remove an incoming carrier from your account.
When you remove a carrier, all numbers associated with the carrier are deleted.
DELETE
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/
HTTP Status Code: 204