Skip to main content
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.
​
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
}

​
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

import plivo

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

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

​
Get an Account Phone Number

Retrieve details of a specific phone number. 
GET https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/

​
Example

import plivo

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

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

​
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_id
string
ID of an approved compliance record to link to this number. The compliance record must match the number’s country and type. See 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.

​
Example

import plivo

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

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

​
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

import plivo

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

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

​
Response

HTTP Status Code: 204