Phone Numbers API

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

string

Phone number that can be purchased.

string

Area code of the number.

string

City of the number. Returns null for national numbers.

string

Country of the number.

string

City and country of the number.

string

Rate center. US and Canada only.

string

Local access and transport area. US and Canada only.

string

Number type. Values: fixed, mobile, or tollfree.

string

Number subtype. Values: fixed, mobile, tollfree, national, or local.

string

One-time setup fee in USD.

string

Monthly rental fee in USD.

boolean

Whether the number can receive SMS.

string

Cost per SMS received in USD.

boolean

Whether the number can receive MMS.

string

Cost per MMS received in USD.

boolean

Whether the number can receive calls.

string

Cost per minute for calls in USD.

string

Verification requirement. Values: city-address, country-address, terms-and-conditions, or null.

string

Description of verification requirements.

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

string

required

ISO 3166 alpha-2 country code of the country.

string

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

string

Pattern to match. For example, 415 returns numbers starting with 1415.

integer

Six-digit prefix filter. US and Canada only.

boolean

Expand search to local calling area of npanxx.

string

Region name (e.g., Frankfurt). For fixed type only.

string

City name. For local type only.

string

Filter by capabilities. Values: voice, sms, mms, voice,sms, or voice,sms,mms.

integer

LATA filter. US and Canada only.

string

Rate center filter. US and Canada only.

integer

Results per page. Maximum 20, default 20.

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)

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

string

Application to assign. Defaults to default_number_app.

string

Enable CNAM lookup. Values: enabled or disabled. US only.

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 the application was filed for a subaccount, buy the number for that subaccount (pass subaccount). See the Compliance API.If you omit it, Plivo auto-selects the most recent accepted application that matches the number’s country and type:

With subaccount: one filed for that subaccount first, then one of your main account’s.
Without subaccount: one of your main account’s.

Plivo never auto-selects an application filed for a different 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. A number linked to a compliance application filed for a subaccount stays on that subaccount; see the subaccount parameter there.

Example

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"
}

Compliance Errors

Renting a number that requires compliance, such as an India number, needs a compliance application in accepted status. Requests that don’t meet this condition return 400 bad request:

Condition	Error message
No `compliance_application_id` passed and no accepted application Plivo can auto-select for this purchase (see `compliance_application_id` above)	`compliance_application_id is required to rent this number. Refer to https://www.plivo.com/docs/numbers/rent-india-numbers for details.`
The `compliance_application_id` passed is not in `accepted` status	`Compliance application must be in 'accepted' status. Current status: 'submitted'.`
The `compliance_application_id` passed was filed for a subaccount other than the one the number is bought for	`Compliance application xxx was filed for another sub-account. Use one filed for this number's sub-account, or one of the account's own.`

See India Number KYC for how to resolve each application status.

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

Concepts

API Reference

Phone Numbers API

The PhoneNumber Object

Attributes

Example Object

Search Phone Numbers

Arguments

Example

Response

Buy a Phone Number

Arguments

Example

Response

Compliance Errors

The PhoneNumber Object

Attributes

Example Object

Search Phone Numbers

Arguments

Example

Response

Buy a Phone Number

Arguments

Example

Response

Compliance Errors

Related