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 integerA 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 stringThe 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 stringThe 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 stringThe 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
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

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

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

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

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

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

Response

HTTP Status Code: 204

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
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&amp;type=local&amp;pattern=210&amp;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

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/",
    }
  ]
}

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

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

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