Account Phone Numbers API

Manage phone numbers in your Plivo account

Manage phone numbers that you’ve rented from Plivo or added from your carrier. List, retrieve, update, and unrent numbers.

API Endpoint

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

Associated subaccount (null if main account).

added_on · string

Date rented. Format: YYYY-MM-DD.

application · string

Linked application URI.

carrier · string

Plivo or incoming carrier name.

region · string

City and country.

number_type · string

Number type. Values: local, fixed, tollfree, mobile, national.

monthly_rental_rate · string

Monthly fee (USD).

renewal_date · string

Next billing date. Format: YYYY-MM-DD.

sms_enabled · boolean

Can receive SMS.

sms_rate · string

Cost per SMS (USD).

mms_enabled · boolean

Can receive MMS.

mms_rate · string

Cost per MMS (USD).

voice_enabled · boolean

Can receive calls.

voice_rate · string

Cost per minute (USD).

cnam_lookup · string

CNAM lookup status. Values: enabled, disabled, null.

cnam · string

Caller ID name for outbound calls.

tendlc_registration_status · string

10DLC status. Values: UNREGISTERED, PROCESSING, COMPLETED.

tendlc_campaign_id · string

Linked 10DLC campaign ID.

toll_free_sms_verification · string

TF SMS verification. Values: UNVERIFIED, PENDING_VERIFICATION, VERIFIED.

profile_uuid · string

UUID of the linked business profile. null if no profile is linked.

caller_reputation_status · string

Caller Reputation activation status. Values: PENDING, ACTIVE, FAILED, NOT_ENROLLED, null.

resource_uri · string

URI to the number resource.

Example Object

{
  "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,
  "profile_uuid": null,
  "caller_reputation_status": null
}

---

List Account Phone Numbers

Returns all phone numbers in your account.

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

Query Parameters

type · string

Filter by type. Values: local, mobile, fixed, national, tollfree.

number_startswith · string

Filter by prefix.

subaccount · string

Filter by subaccount.

alias · string

Filter by exact alias.

services · string

Filter by services. Values: voice, sms, mms, or combinations.

cnam_lookup · string

Filter by CNAM status. Values: enabled, disabled.

renewal_date · string

Filter by renewal date. Format: YYYY-MM-DD. Supports variants: renewal_date__gt, renewal_date__gte, renewal_date__lt, renewal_date__lte.

tendlc_registration_status · string

Filter by 10DLC status. Values: unregistered, in_progress, registered.

tendlc_campaign_id · string

Filter by campaign ID.

toll_free_sms_verification · string

Filter by TF verification status. Values: unverified, pending_verification, verified.

limit · integer

Results per page. Max: 20. Default: 20.

offset · integer

Pagination offset.

Example

Python

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.numbers.list(limit=10, type='local')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.numbers.list({ limit: 10, type: 'local' })
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.numbers.list(limit: 10, type: 'local')
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->numbers->list(['limit' => 10, 'type' => 'local']);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.number.Number;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<Number> response = Number.lister()
    .limit(10)
    .list();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Number.List(limit: 10, type: "local");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Numbers.List(plivo.NumberListParams{Limit: 10})
    fmt.Println(response)
}

curl "https://api.plivo.com/v1/Account/{auth_id}/Number/?limit=10&type=local" \
  -u '<auth_id>:<auth_token>'

---

Get an Account Phone Number

Retrieve details of a specific phone number.

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

Example

Python

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.numbers.get(number='17609915566')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.numbers.get('17609915566')
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.numbers.get('17609915566')
puts response

curl "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>'

---

Update an Account Phone Number

Change the application, subaccount, or alias for a phone number.

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

Arguments

app_id · string

Application to assign (or Zentrunk inbound trunk_id).

subaccount · string

Subaccount auth_id to transfer number to.

alias · string

Alias for the number.

compliance_application_id · string

UUID of an accepted compliance application to link to this number. The application must match the number’s country and type. This parameter only takes effect while the number is pending activation — for numbers that are already active, use the Bulk Link endpoint instead. See the Compliance API for details.

cnam_lookup · string

CNAM lookup. Values: enabled, disabled. US only.

cnam · string

Caller ID name for outbound calls.

cnam_callback_url · string

URL for CNAM registration updates.

cnam_callback_method · string

HTTP method. Values: GET, POST. Default: POST.

caller_reputation · string

Enable or disable Caller Reputation for this number. Values: enabled, disabled. When set to enabled, profile_uuid is required. US local and toll-free numbers only. Early access beta. See Caller Reputation for details.

profile_uuid · string

UUID of the business profile to associate with this number. Required when caller_reputation is set to enabled.

caller_reputation_callback_url · string

URL to receive Caller Reputation status update notifications.

caller_reputation_callback_method · string

HTTP method for the callback. Values: GET, POST. Default: POST.

Example

Python

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.numbers.update(number='17609915566', alias='Main Line')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.numbers.update('17609915566', { alias: 'Main Line' })
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.numbers.update('17609915566', alias: 'Main Line')
puts response

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"alias": "Main Line"}'

Response

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

---

Unrent a Number

Remove a phone number from your account. This operation cannot be undone.

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

Example

Python

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.numbers.delete(number='17609915566')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.numbers.unrent('17609915566')
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.numbers.delete('17609915566')
puts response

curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>'

Response

HTTP Status Code: 204

---

Related

• Phone Numbers - Search and buy numbers
• Incoming Carriers - Add numbers from your carrier
• Regulatory Compliance - Verification requirements
• Caller Reputation - Register your business identity to reduce spam flagging