Account Phone Numbers API

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

string

The phone number.

string

Alias for the phone number.

string

Associated subaccount (null if main account).

string

Date rented. Format: YYYY-MM-DD.

string

Linked application URI.

string

Plivo or incoming carrier name.

string

City and country.

string

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

string

Monthly fee (USD).

string

Next billing date. Format: YYYY-MM-DD.

boolean

Can receive SMS.

string

Cost per SMS (USD).

boolean

Can receive MMS.

string

Cost per MMS (USD).

boolean

Can receive calls.

string

Cost per minute (USD).

string

CNAM lookup status. Values: enabled, disabled, null.

string

Caller ID name for outbound calls.

string

10DLC status. Values: UNREGISTERED, PROCESSING, COMPLETED.

string

Linked 10DLC campaign ID.

string

TF SMS verification. Values: UNVERIFIED, PENDING_VERIFICATION, VERIFIED.

string

UUID of the linked business profile. null if no profile is linked.

string

Merged Caller Reputation status for the number across carrier networks. Values: PENDING, ACTIVE, FAILED, NOT_REGISTERED, null. Read caller_reputation_by_carrier for each network’s real status.

object

Per-carrier Caller Reputation status for the number, keyed by carrier network: at&t and t-mobile, plus verizon when it was explicitly requested (reported as NOT_SUPPORTED). Each entry contains status, reason_code, reason, and updated_at. See Status values.

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

string

Filter by type. Values: local, mobile, fixed, national, tollfree.

string

Filter by prefix.

string

Filter by subaccount.

string

Filter by exact alias.

string

Filter by services. Values: voice, sms, mms, or combinations.

string

Filter by CNAM status. Values: enabled, disabled.

string

Filter by renewal date. Format: YYYY-MM-DD. Supports variants: renewal_date__gt, renewal_date__gte, renewal_date__lt, renewal_date__lte.

string

Filter by 10DLC status. Values: unregistered, in_progress, registered.

string

Filter by campaign ID.

string

Filter by TF verification status. Values: unverified, pending_verification, verified.

integer

Results per page. Max: 20. Default: 20.

integer

Pagination offset.

Example

import plivo

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

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

const plivo = require('plivo');

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

client.numbers.list({ limit: 10, type: 'local' })
    .then(response => console.log(response));

require 'plivo'

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

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

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

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

$response = $client->numbers->list(['limit' => 10, 'type' => 'local']);
print_r($response);

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

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

ListResponse<Number> response = Number.lister()
    .limit(10)
    .list();
System.out.println(response);

using Plivo;

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

var response = api.Number.List(limit: 10, type: "local");
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.Numbers.List(plivo.NumberListParams{Limit: 10})
    fmt.Println(response)
}

curl "https://api.plivo.com/v1/Account/{auth_id}/Number/?limit=10&type=local" \
  -u '<auth_id>:<auth_token>'

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)

const plivo = require('plivo');

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

client.numbers.get('17609915566')
    .then(response => console.log(response));

require 'plivo'

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

response = client.numbers.get('17609915566')
puts response

curl "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>'

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

string

Application to assign (or Zentrunk inbound trunk_id).

string

Subaccount auth_id to transfer number to.

Number linked to a compliance application filed for a subaccount: it can’t move to another subaccount or back to your main account. To change the owner, unrent it and buy it again for the new owner. Unrenting can’t be undone.
Exception, number still pending activation: you can move it if the same request also passes a compliance_application_id filed for the destination subaccount or for your main account.

string

Alias for the number.

string

UUID of an accepted compliance application to link to this number. The application must match the number’s country and type. It must be filed for your main account or for the subaccount the number belongs to after this update. This parameter only takes effect while the number is pending activation — for numbers that are already active, use the Bulk Link endpoint instead. See the Compliance API for details.

string

CNAM lookup. Values: enabled, disabled. US only.

string

Caller ID name for outbound calls.

string

URL for CNAM registration updates.

string

HTTP method. Values: GET, POST. Default: POST.

string

Enable or disable Caller Reputation for this number. Values: enabled, disabled. When set to enabled, profile_uuid is required and the profile must have a registered business with at least one carrier network approved — the number attaches on every approved network, and the response reports each network’s status. If no network is approved, the request returns a 400. US local and toll-free numbers only. Early access beta. See Caller Reputation for the full flow.

string

UUID of the business profile to associate with this number. Required when caller_reputation is set to enabled.

string

deprecated

Deprecated. Set url on the profile instead — see Status callbacks. Plivo accepts this parameter during the migration period and ignores it after.

string

deprecated

Deprecated. Set method on the profile instead. Plivo accepts this parameter during the migration period and ignores it after.

Example

import plivo

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

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

const plivo = require('plivo');

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

client.numbers.update('17609915566', { alias: 'Main Line' })
    .then(response => console.log(response));

require 'plivo'

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

response = client.numbers.update('17609915566', alias: 'Main Line')
puts response

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"alias": "Main Line"}'

Response

{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}

Compliance Errors

An update that changes subaccount or passes compliance_application_id can return these errors, each with 400 bad request:

Condition	Error message
Moving a number linked to a subaccount’s application to another owner	`Number 912212345678 is linked to compliance application xxx, which was filed for its sub-account. Keep the number on that sub-account, or release it and rent it again for the new one.`
The `compliance_application_id` passed was filed for a different subaccount	`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.`
The number’s linked application could not be checked (retry)	`Could not verify the compliance application linked to number 912212345678. Please try again.`

To release a number, unrent it. See India Number KYC for how compliance applications filed for subaccounts work.

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)

const plivo = require('plivo');

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

client.numbers.unrent('17609915566')
    .then(response => console.log(response));

require 'plivo'

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

response = client.numbers.delete('17609915566')
puts response

curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/Number/17609915566/" \
  -u '<auth_id>:<auth_token>'

Response

HTTP Status Code: 204

Phone Numbers - Search and buy numbers
Incoming Carriers - Add numbers from your carrier
Regulatory Compliance - Verification requirements
Caller Reputation - Register your business identity to reduce spam flagging

Concepts

API Reference

Account Phone Numbers API

The AccountPhoneNumber Object

Attributes

Example Object

List Account Phone Numbers

Query Parameters

Example

Get an Account Phone Number

Example

Update an Account Phone Number

Arguments

Example

Response

Compliance Errors

Unrent a Number

Example

Response

The AccountPhoneNumber Object

Attributes

Example Object

List Account Phone Numbers

Query Parameters

Example

Get an Account Phone Number

Example

Update an Account Phone Number

Arguments

Example

Response

Compliance Errors

Unrent a Number

Example

Response

Related