Get Started with Phone Numbers

    These actions can be performed with the PhoneNumber API:

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

    Prerequisites

    1. Sign up for a free Plivo trial account.
    2. Check out our server SDKs and install the SDK for the programming language you want to use.
    3. Buy a Plivo phone number. You need a Plivo phone number to receive calls. You can buy a Plivo phone number in more than 20 countries by visiting Phone Numbers > Buy Numbers in the Plivo console. Check the Voice API coverage page to see the supported countries.
    4. Use a web hosting service to host your web application. Many inexpensive cloud hosting providers charge just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

    Search for New Numbers

    This API call lets you search for fixed, mobile, and toll-free numbers available on Plivo. You can search on any combination of the two-letter country code, number pattern, number type, and region. The call returns a list of numbers that match the search criteria and that are available to rent.

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

    Code

    1
    2
    3
    4
    5
    6
    
           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
    
           require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.phone_numbers.search('GB')
      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
    
           var plivo = require('plivo');
    
    (function main() {
        'use strict';
        
        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
    
           <?php
    
    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
    
           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;
    
    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
    
           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
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
           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 {
    		panic(err)
    	}
    	response, err := client.PhoneNumbers.List(
    		plivo.PhoneNumberListParams{CountryISO: "GB"},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }
           
    
    1
    2
    3
    
           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
           
    

    Rent a Number

    You can use a number you retrieve from the search above as input to rent the number for your Plivo account. Upon successful execution, the number will appear in your Plivo dashboard and be available for all the actions in the Number API.

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

    Code

    1
    2
    3
    4
    5
    6
    
           import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    response = client.numbers.buy(number='441273257545')
    print(response)
           
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
           require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.phonenumbers.buy('441273257545')
      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
    
           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.buy("441273257545", // number
        ).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
    
           <?php
    
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("<auth_id>","<auth_token>");
    
    try {
        $response = $client->phonenumbers->buy('441273257545');
        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
    
           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.number.PhoneNumberCreateResponse;
    
    class PhoneNumberCreate {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                PhoneNumberCreateResponse response = PhoneNumber.creator("441273257545")
                    .create();
    
                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
    
           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.Buy(number:"441273257545");
                    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
    
           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 {
    		panic(err)
    	}
    	response, err := client.PhoneNumbers.Create(
    		"441273257545", 
    		plivo.PhoneNumberCreateParams{},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }
           
    
    1
    2
    3
    4
    
           curl -X POST -i --user AUTH_ID:AUTH_TOKEN 
        -H "Content-Type: application/json"  
        https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/444444444444/
           
    

    Next Step

    Learn how to query the Pricing API.