Search Phone Numbers

Latest Legacy

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 ?. For example, in order to search for phone numbers in the US starting with 415 prefix, Pattern = 415. Filtered results will be of form '1415XXXXXXX'
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. mms: Indicates that phone numbers that can receive MMS are to be returned. voice,sms: Indicates that phone numbers which can receive both calls and SMS are to be returned. voice,sms,mms: Indicates that phone numbers that can receive calls, SMS and MMS are to be returned.
city string	Filter phone number based on the city name. This filter is only applicable when the type is Local.
lata optional	Filters phone numbers in a LATA. This filter is applicable only for US and Canada.
npanxx 6-digit integer	Filters Local US and CA numbers based on the provided 6-digit prefix. The filter is only applicable if the country is US or CA. For example, to search for 1 (737) 977 XXXX, 'npanxx' = 737 977. To be used in combination with local_calling_area filter.
local_calling_area boolean	If set to True, expands the search results to include phone numbers that are local to the searched npanxx. The filter is only applicable if npanxx is provided. Defaults to False.
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	Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about offset based pagination here.

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.phone_numbers.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
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)
}

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
auth_id = "Your AUTH_ID"
auth_token = "Your AUTH_TOKEN"

p = plivo.RestAPI(auth_id, auth_token)

# Search for new number
params = {
    'country_iso': 'US', # The ISO code A2 of the country
    'type' : 'local', # The type of number you are looking for. The possible number types are local, national and tollfree.
    'pattern' : '210', # Represents the pattern of the number to be searched. 
    'region' : 'Texas' # This filter is only applicable when the number_type is local. Region based filtering can be performed.
}

response = p.search_phone_numbers(params)
print str(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'plivo'
include Plivo

AUTH_ID = "Your AUTH_ID"
AUTH_TOKEN = "Your AUTH_TOKEN"


p = RestAPI.new(AUTH_ID, AUTH_TOKEN)

# Search for new number
params = {
    'country_iso' => 'US', # The ISO code A2 of the country
    'type' => 'local', # The type of number you are looking for. The possible number types are local, national and tollfree.
    'pattern' => '210', # Represents the pattern of the number to be searched.
    'region' => 'Texas' # This filter is only applicable when the number_type is local. Region based filtering can be performed.
}

response = p.search_phone_number(params)
print response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var plivo = require('plivo');
var p = plivo.RestAPI({
  authId: 'Your AUTH_ID',
  authToken: 'Your AUTH_TOKEN'
});

// Search for new number
var params = { 
    'country_iso': 'US', // The ISO code A2 of the country
    'type' : 'local', // The type of number you are looking for. The possible number types are local, national and tollfree.
    'pattern' : '210', // Represents the pattern of the number to be searched. 
    'region' : 'Texas' // This filter is only applicable when the number_type is local. Region based filtering can be performed.
};

p.search_phone_numbers(params, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
    require 'vendor/autoload.php';
    use Plivo\RestAPI;
    
    $auth_id = "Your AUTH_ID";
    $auth_token = "Your AUTH_TOKEN";
    
    $p = new RestAPI($auth_id, $auth_token);
    
    # Search for new number
    $params = array(
        'country_iso' => 'US', # The ISO code A2 of the country
        'type' => 'local', # The type of number you are looking for. The possible number types are local, national and tollfree.
        'pattern' => '210', # Represents the pattern of the number to be searched. 
        'region' => 'Texas' # This filter is only applicable when the number_type is local. Region based filtering can be performed.
    );
    $response = $p->search_phone_numbers($params);
    print_r ($response);  
?>

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
31
32
package plivoexample;

import java.util.LinkedHashMap;

import com.plivo.helper.api.client.*;
import com.plivo.helper.api.response.number.NumberSearchFactory;
import com.plivo.helper.exception.PlivoException;

public class App {

    public static void main(String[] args) throws IllegalAccessException {

        String auth_id = "Your AUTH_ID";
        String auth_token = "Your AUTH_TOKEN";
        
        RestAPI api = new RestAPI(auth_id, auth_token, "v1");

        // Search for a phone number
        LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
        parameters.put("country_iso","US");
        parameters.put("type","local");
        parameters.put("pattern","210");
        parameters.put("region","Texas");

        try {
            PhoneNumberSearchFactory resp = api.searchPhoneNumber(parameters);
            System.out.println(resp);
        }catch (PlivoException e){  
            System.out.println(e.getLocalizedMessage());
        } 
    }
}

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
using System;
using System.Collections.Generic;
using RestSharp;
using Plivo.API;

namespace apps
{
    class Program
    {
        static void Main(string[] args)
        {
            RestAPI plivo = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");
            
            // Search for a new phone number
            IRestResponse<PhoneNumberList> resp = plivo.search_phone_numbers(new Dictionary<string,string>()
            {
                {"country_iso","US"}, // The ISO code A2 of the country
                {"type","local"}, // The type of number you are looking for. The possible number types are local, national and tollfree.
                {"pattern","210"}, // Represents the pattern of the number to be searched.
                {"region","Texas"} // This filter is only applicable when the number_type is local. Region based filtering can be performed.
            });

            Console.WriteLine(resp.Content);
        }
    }
}

Rate this page

🥳 Thank you! It means a lot to us!