Skip to main content
Search for and purchase phone numbers from Plivo. You can search for local, toll-free, national, mobile, and fixed phone numbers that match specific criteria. API Endpoint 
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/

​
The PhoneNumber Object

​
Attributes

​
number
string
Phone number that can be purchased.
​
prefix
string
Area code of the number.
​
city
string
City of the number. Returns null for national numbers.
​
country
string
Country of the number.
​
region
string
City and country of the number.
​
rate_center
string
Rate center. US and Canada only.
​
lata
string
Local access and transport area. US and Canada only.
​
type
string
Number type. Values: fixed, mobile, or tollfree.
​
sub_type
string
Number subtype. Values: fixed, mobile, tollfree, national, or local.
​
setup_rate
string
One-time setup fee in USD.
​
monthly_rental_rate
string
Monthly rental fee in USD.
​
sms_enabled
boolean
Whether the number can receive SMS.
​
sms_rate
string
Cost per SMS received in USD.
​
mms_enabled
boolean
Whether the number can receive MMS.
​
mms_rate
string
Cost per MMS received in USD.
​
voice_enabled
boolean
Whether the number can receive calls.
​
voice_rate
string
Cost per minute for calls in USD.
​
restriction
string
Verification requirement. Values: city-address, country-address, terms-and-conditions, or null.
​
restriction_text
string
Description of verification requirements.
​
resource_uri
string
URI to the phone number resource.

​
Example Object

{
  "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/14155559186/"
}

​
Search Phone Numbers

Returns available phone numbers matching your criteria. 
GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/

​
Arguments

​
country_iso
string
required
ISO 3166 alpha-2 country code of the country.
​
type
string
Number type filter. Values: tollfree, local, mobile, national, or fixed.
​
pattern
string
Pattern to match. For example, 415 returns numbers starting with 1415.
​
npanxx
integer
Six-digit prefix filter. US and Canada only.
​
local_calling_area
boolean
Expand search to local calling area of npanxx.
​
region
string
Region name (e.g., Frankfurt). For fixed type only.
​
city
string
City name. For local type only.
​
services
string
Filter by capabilities. Values: voice, sms, mms, voice,sms, or voice,sms,mms.
​
lata
integer
LATA filter. US and Canada only.
​
rate_center
string
Rate center filter. US and Canada only.
​
limit
integer
Results per page. Maximum 20, default 20.
​
offset
integer
Pagination offset. Default 0.

​
Example

import plivo

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

response = client.numbers.search(country_iso='US', type='local', pattern='415')
print(response)

​
Response

{
  "api_id": "859428b0-1c88-11e4-a2d1-22000ac5040c",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 9
  },
  "objects": [
    {
      "number": "14154009186",
      "prefix": "415",
      "city": "SAN FRANCISCO",
      "country": "UNITED STATES",
      "type": "fixed",
      "sub_type": "local",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "voice_enabled": true,
      "restriction": null,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/PhoneNumber/14154009186/"
    }
  ]
}

​
Buy a Phone Number

Purchase a phone number and add it to your account. 
POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/{number}/

​
Arguments

​
app_id
string
Application to assign. Defaults to default_number_app.
​
cnam_lookup
string
Enable CNAM lookup. Values: enabled or disabled. US only.
​
compliance_application_id
string
UUID of an accepted compliance application to attach to the number at purchase. The application’s country and number type must match the number. If omitted, Plivo auto-selects your most recent applicable compliance application. See the Compliance API.
​
subaccount
string
Auth ID of a subaccount to assign the number to at purchase. Requires main-account credentials (see note below).
If the number requires verification documents, the number status will be pending until documents are approved.
Call this endpoint with main-account credentials. Phone numbers are billed and owned at the main-account level, so a request made with subaccount credentials returns 404 not found even when Search works with the same credentials. To buy a number for a subaccount, call this endpoint with main-account credentials and pass the subaccount parameter. To move an already-rented number to a subaccount, use the Update an Account Phone Number endpoint’s subaccount parameter.

​
Example

import plivo

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

response = client.numbers.buy(number='14155559186')
print(response)

​
Response

{
    "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
    "message": "created",
    "numbers": [
        {
            "number": "14155559186",
            "status": "Success"
        }
    ],
    "status": "fulfilled"
}