Search Phone Numbers

Returns a list of phone numbers that are available for purchase. You can search for tollfree, mobile, local, national and fixed phone numbers. The API allows you to filter phone numbers based on the country_iso, pattern, type and region.

API Endpoint

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

Arguments

country_iso Required

The ISO country code of the country. For more information on supported countries, refer to our incoming Voice and SMS coverage.

type string

Filters by the type of the phone number. Possible values are tollfree, local, mobile, national and fixed.

pattern string

A pattern to match the phone number with. Phone numbers starting with (country calling code + pattern) are filtered in. The allowed values are A-Z, 0-9, *, and ?.

region string min.length is 2

This filter is only applicable when the type is fixed. If the type is not provided, it is assumed to be fixed. You could use the exact name of the region, for instance region=Frankfurt for a phone number in Frankfurt.

services string

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

  • voice: Indicates that phone numbers which can receive calls are to be returned.

  • sms: Indicates that phone numbers which can receive SMS are to be returned.

  • voice,sms: Indicates that phone numbers which can receive both calls and SMS are to be returned.

lata optional

Filters phone numbers in a LATA. This filter is applicable only for US and Canada.

rate_center optional

Filters phone numbers based on the rate center. This filter is applicable only for US and Canada.

limit default is 20

A limit on the number phone numbers to be returned. limit can range between 1 and 20, and the default is 20.

offset integer

A pagination cursor to denote the number of objects by which the results should be offset. For instance, if your search request has a result of 100 objects with limit = 10 and offset = 5, then objects with indices 51 through 60 are returned.

Returns

A dictionary with objects property that contains a list of up to limit phone numbers. Each tuple in the list is a separate PhoneNumber object. An empty list is returned if there are no phone numbers matching the provided criteria.

Response

HTTP Status Code: 200

{
  "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": "NEW YORK",
      "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/MAXXXXXXXXXXXXXXXXXX/PhoneNumber/14154009186/",
    },
    {
      "number": "14154009187",
      "prefix": "415",
      "city": "NEW YORK",
      "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/MAXXXXXXXXXXXXXXXXXX/PhoneNumber/14154009187/",
    }
  ]
}

Example Request

1
2
3
4
5
import plivo

client = plivo.RestClient()
response = client.numbers.search(country_iso='GB')
print(response)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#
# Example for PhoneNumber List
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN")

begin
  response = api.phonenumbers.search(
    'GB',
    limit: 5
  )
  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
// Example for PhoneNumber list

var plivo = require('plivo');

(function main() {
    'use strict';
    
    // As the auth_id and auth_token are unspecified, Plivo will fetch them from the PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN environment variables.
    var client = new plivo.Client();
    client.numbers.search(
        "GB", // country iso
    ).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
<?php
/**
 * Example for PhoneNumber list
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");

try {
    $response = $client->phonenumbers->list(
        'GB'
    );
    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
package com.plivo.api.samples.phonenumber;

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

/**
* Example for PhoneNumber list
*/
class PhoneNumberList {
    public static void main(String [] args) {
        Plivo.init();
        try {
            ListResponse<PhoneNumber> response = PhoneNumber.lister("GB")
                .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
/**
 * Example for PhoneNumber 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("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");
            try
            {
                var response = api.Phonenumber.List(
                    countryIso:"GB"
                );
                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}/PhoneNumber/?country_iso=US&amp;type=local&amp;pattern=210&amp;region=Texas
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example for PhoneNumber list
package main

import "fmt"
import "github.com/plivo/plivo-go"
 
func main() {
	client, err := plivo.NewClient("", "", &plivo.ClientOptions{})
	if err != nil {
		panic(err)
	}
	response, err := client.PhoneNumbers.List(
		plivo.PhoneNumberListParams{
			CountryISO: "GB",
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Response: %#v\n", response)
}