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.
    • 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.

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