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 ?. 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:
|
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
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/?country_iso=US&type=local&pattern=210&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)
}