Search Phone Numbers

    Returns a list of phone numbers that are available for purchase. You can search for toll-free, mobile, local, national, and fixed phone numbers. The API lets you filter phone numbers based on several criteria.

    API Endpoint

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

    Arguments

    country_iso Requiredstring

    The ISO 3166 alpha-2 country code of the country. To see what number types we support in each country, visit our voice and SMS coverage pages.

    type string

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

    pattern string

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

    For example, to search for phone numbers in the US starting with a 415 prefix, specify Pattern = 415. Filtered results will be in the form "1415XXXXXXX"

    npanxx six-digit integer

    Filters local US and CA numbers based on the provided six-digit prefix. The filter is applicable only 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 the 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. Read more about local calling.

    Defaults to false.

    Note: If local_calling_area is set to true, phone numbers in the search results might not match the searched npanxx. All phone numbers in the search results will be in the local calling radius of the searched npanxx.
    region string min. length is 2

    Filters by the exact name of a region: for instance, region=Frankfurt.

    This filter is applicable only when the type is fixed. If no type is provided, type is assumed to be fixed.

    services string

    Filters phone numbers that provide the selected services. Allowed 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.
    city string

    Filters based on the city name.

    This filter is applicable only when the type is local.

    lata

    Filters by LATA.

    This filter is applicable only for US and Canada.

    rate_center

    Filters by rate center.

    This filter is applicable only for US and Canada.

    limit default is 20

    A limit on the number of 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.

    Returns

    A dictionary with an 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",
      "error" : "",
      "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 9
      },
      "objects": [
        {
          "number": "14154009186",
          "prefix": "415",
          "city": "SAN FRANCISCO",
          "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": "SAN FRANCISCO",
          "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('<auth_id>','<auth_token>')
    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("<auth_id>","<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';
        
       // 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.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("<auth_id>","<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("<auth_id>","<auth_token>");
            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("<auth_id>","<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
    22
    23
    
    // Example for PhoneNumber list
    package main
    
    import "fmt"
    import "github.com/plivo/plivo-go"
     
    func main() {
    	client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	response, err := client.PhoneNumbers.List(
    		plivo.PhoneNumberListParams{
    			CountryISO: "GB",
    		},
    	)
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Printf("Response: %#v\n", response)
    }