Skip to main content

Documentation Index

Fetch the complete documentation index at: https://plivo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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