Phone Numbers API

Search and buy phone numbers from Plivo’s inventory

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

Python

import plivo

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

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

const plivo = require('plivo');

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

client.numbers.search('US', { type: 'local', pattern: '415' })
    .then(response => console.log(response));

require 'plivo'

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

response = client.phone_numbers.search('US', type: 'local', pattern: '415')
puts response

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

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

$response = $client->phonenumbers->list('US', ['type' => 'local', 'pattern' => '415']);
print_r($response);

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

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

ListResponse<PhoneNumber> response = PhoneNumber.lister("US")
    .type("local")
    .pattern("415")
    .list();
System.out.println(response);

using Plivo;

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

var response = api.PhoneNumber.List(countryIso: "US", type: "local", pattern: "415");
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.PhoneNumbers.List(plivo.PhoneNumberListParams{
        CountryISO: "US",
        Type:       "local",
        Pattern:    "415",
    })
    fmt.Println(response)
}

curl "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/?country_iso=US&type=local&pattern=415" \
  -u '<auth_id>:<auth_token>'

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

Python

import plivo

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

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

const plivo = require('plivo');

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

client.numbers.buy('14155559186')
    .then(response => console.log(response));

require 'plivo'

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

response = client.phone_numbers.buy('14155559186')
puts response

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

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

$response = $client->phonenumbers->buy('14155559186');
print_r($response);

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

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

PhoneNumberCreateResponse response = PhoneNumber.creator("14155559186").create();
System.out.println(response);

using Plivo;

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

var response = api.PhoneNumber.Buy(number: "14155559186");
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.PhoneNumbers.Create("14155559186", plivo.PhoneNumberCreateParams{})
    fmt.Println(response)
}

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/14155559186/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json"

Response

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

---

Related

• Account Phone Numbers - Manage your rented numbers
• Regulatory Compliance - Verification requirements
• Number Porting - Port numbers to Plivo