Latest Legacy

List account phone numbers

Returns a list of phone numbers that you’ve rented from Plivo or added from your carrier.

API Endpoint

GET https://api.plivo.com/v1/Account/{auth_id}/Number/

Arguments

type string

The type of number. You can filter by local, mobile, fixed, national, or toll-free numbers.

number_startswith string

Only show phone numbers that begin with this pattern.

subaccount string

Returns phone numbers associated with this subaccount.

alias string

Returns phone numbers that exactly match this alias.

services string

Filters phone numbers that provide the selected services. Possible values are:

  • voice: Indicates that phone numbers that can receive calls are to be returned.
  • sms: Indicates that phone numbers that can receive SMS messages are to be returned.
  • mms: Indicates that phone numbers that can receive MMS messages are to be returned.
  • voice,sms: Indicates that phone numbers that can receive both calls and SMS messages are to be returned.
  • voice,sms,mms: Indicates that phone numbers that can receive calls and SMS and MMS messages are to be returned.
tendlc_registration_status string

The 10DLC registration status of US local numbers. Valid values:

  • unregistered: returns a list of numbers that are not linked to a campaign.
  • in_progress: returns a list of numbers that are in the process of being linked to campaigns.
  • registered: returns a list of numbers that are linked to campaigns.
tendlc_campaign_id string

10DLC campaign ID that the phone number is linked to. You can filter US local numbers that are linked to a specific campaign.

toll_free_sms_verification string

SMS verification status for SMS-enabled US/Canada toll-free numbers. Valid values:

  • unverified: returns a list of SMS-enabled US/CA toll-free numbers that are not verified.
  • pending_verification: returns a list of SMS-enabled US/CA toll-free numbers that are pending verification.
  • verified: returns a list of SMS-enabled US/CA toll-free numbers that are verified for enhanced outbound SMS limits.
limit integer

Denotes the number of results to display per page. The maximum number of results that can be fetched is 20. Defaults to 20.

offset integer

Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about offset-based pagination.

Returns

A dictionary with an objects property that contains a list of up to limit account phone numbers. Each tuple in the list is a separate AccountPhoneNumber object. Plivo returns an empty list if there are no phone numbers in the account that match the provided criteria.

Response

HTTP Status Code: 200

{
  "api_id": "114de006-1c95-11e4-8a4a-123140008edf",
  "meta": {
    "limit": 2,
    "next": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Number/?limit=3&offset=3",
    "offset": 0,
    "previous": null,
    "total_count": 20
  },
  "objects": [{
      "number": "18135401302",
      "alias": null,
      "sub_account": null,
      "added_on": "2022-08-05",
      "application": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Application/29986316244302815/",
      "carrier": "Plivo",
      "region": "Florida, UNITED STATES",
      "number_type": "local",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "sms_rate": "0.00000",
      "voice_enabled": true,
      "voice_rate": "0.00850",
      "resource_uri": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Number/18135401302/",
      "tendlc_campaign_Id":"2FA_campaign",
      "tendlc_registration_status":"COMPLETED"
      "toll_free_sms_verification":null
    },
    {
      "number": "14153661106",
      "alias": "",
      "sub_account": null,
      "added_on": "2022-01-01",
      "application": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Application/16632559604105954/",
      "carrier": "Plivo",
      "region": "BELVEDERE, UNITED STATES",
      "number_type": "local",
      "monthly_rental_rate": "0.80000",
      "sms_enabled": true,
      "sms_rate": "0.00000",
      "voice_enabled": true,
      "voice_rate": "0.00850",
      "resource_uri": "/v1/Account/MAXXXXXXXXXXXXXXXXXX/Number/14153661106/",
      "tendlc_campaign_Id":"Product_Marketing",
      "tendlc_registration_status":"COMPLETED",
      "toll_free_sms_verification":null
    }
  ]
}

Example Request

1
2
3
4
5
6
7
8
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.numbers.list(
    limit=5,
    offset=0,
    type='fixed', )
print(response)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#
# Example for Number List
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

begin
  response = api.numbers.list(
    limit: 5,
    offset: 0
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Example for Number list

var plivo = require('plivo');

(function main() {
    'use strict';
    
   // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
    var client = new plivo.Client("<auth_id>","<auth_token>");
    client.numbers.list(
        {
            limit: 5,
            offset: 0,
        },
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
/**
 * Example for Number list
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");

try {
    $response = $client->numbers->list(
        [
        	'limit' => 4,
        	'offset' => 4
        ]
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
package com.plivo.api.samples.number;

import java.io.IOException;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.number.Number;
import com.plivo.api.models.base.ListResponse;

/**
* Example for Number list
*/
class NumberList {
    public static void main(String [] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            ListResponse<Number> response = Number.lister()
                .limit(5)
                .offset(0)
                .list();

            System.out.println(response);
        } catch (PlivoRestException | IOException e) {
            e.printStackTrace();
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/**
 * Example for Number List
 */
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            try
            {
                var response = api.Number.List(
                    limit:5,
                    offset:0
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}
1
2
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Number/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Example for Number list
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Numbers.List(
		plivo.NumberListParams{
			Limit:  5,
			Offset: 0,
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}