Get Started with Account Phone Numbers

    These actions can be performed with the Number API:

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

    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.

    List All Rented Numbers

    This API call returns a list with the details of all numbers rented under your Plivo account.

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

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    
           import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    response = client.numbers.list(
        limit=5,
        offset=0)
    print(response)
           
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
           require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.numbers.list(
        limit: 5,
        offset: 0
      )
      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
    18
    
           var plivo = require('plivo');
    
    (function main() {
        'use strict';
        
        var client = new plivo.Client("<auth_id>","<auth_token>");
        client.numbers.list(
            {
                limit: 5,
                offset: 0,
            },
        ).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
    19
    20
    
           <?php
    
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("<auth_id>","<auth_token>");
    
    try {
        $response = $client->numbers->list(
            [
            	'limit' => 4,
            	'offset' => 4
            ]
        );
        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.number;
    
    import java.io.IOException;
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.number.Number;
    import com.plivo.api.models.base.ListResponse;
    
    class NumberList {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                ListResponse<Number> response = Number.lister()
                    .limit(5)
                    .offset(0)
                    .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
    
           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.Number.List(
                        limit:5,
                        offset:0
                    );
                    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
    22
    23
    24
    
           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.Numbers.List(
    		plivo.NumberListParams{
    			Limit: 5,
    			Offset: 0,
    		},
    	)
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Printf("Response: %#v\n", response)
    }
           
    
    1
    2
    3
    
           curl -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/Number/
           
    

    Get Details of a Rented Number

    This API call returns the details of a single number rented under your Plivo account.

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

    Code

    1
    2
    3
    4
    5
    6
    7
    
           import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    response = client.numbers.get(
        number='17609915566', )
    print(response)
           
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
           require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.numbers.get(
        '17609915566'
      )
      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.get(
            "17609915566", // 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->numbers->get('17609915566');
        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.number;
    
    import java.io.IOException;
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.number.Number;
    import com.plivo.api.models.number.Number;
    
    class NumberGet {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                Number response = Number.getter("17609915566")
                    .get();
    
                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
    
           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.Number.Get(
                        number:"17609915566"
                    );
                    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 {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	response, err := client.Numbers.Get("17609915566")
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Printf("Response: %#v\n", response)
    }
           
    
    1
    2
    3
    
           curl -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/Number/444444444444/
           
    

    Edit a Number

    This API call lets you change the application and subaccount associated with a number you rented.

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

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    
           import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    response = client.numbers.update(
        number='17609915566',
        alias='Updated Alias', )
    print(response)
           
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
           require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.numbers.update(
        '17609915566',
        alias: 'Updated Alias'
      )
      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
    18
    
           var plivo = require('plivo');
    
    (function main() {
        'use strict';
        
        var client = new plivo.Client("<auth_id>","<auth_token>");
        client.numbers.update(
            "17609915566", // number
            {
                alias: "Updated Alias",
            },
        ).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
    
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("<auth_id>","<auth_token>");
    
    try {
        $response = $client->numbers->update(
            '17609915566',
            ['alias' => 'Updated Alias']
        );
        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
    
           package com.plivo.api.samples.number;
    
    import java.io.IOException;
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.number.Number;
    import com.plivo.api.models.number.NumberUpdateResponse;
    
    class NumberUpdate {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                NumberUpdateResponse response = Number.updater("17609915566")
                    .alias("Updated Alias")
                    .update();
    
                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
    
           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.Number.Update(
                        alias:"Updated Alias",
                        number:"17609915566"
                    );
                    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
    22
    23
    24
    
           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.Numbers.Update(
    		"17609915566",
    		plivo.NumberUpdateParams{
    			Alias: "Updated Alias",
    		},
    	)
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Printf("Response: %#v\n", response)
    }
           
    
    1
    2
    3
    4
    5
    
           curl -i --user AUTH_ID:AUTH_TOKEN 
        -H "Content-Type: application/json" 
        -d '{"alias": "testing"}'  
        https://api.plivo.com/v1/Account/{auth_id}/Number/11111111111/
           
    

    This API call lets you link an application to a number you rented.

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

    Code

    This API call lets you unlink an application from a number you rented.

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

    Code

    Relinquish a Number

    This API lets you relinquish a number on Plivo. Upon successful execution, the number will no longer be usable or accessible from your Plivo account. This operation cannot be undone.

    DELETE https://api.plivo.com/v1/Account/{auth_id}/Number/{number}/

    Code

    1
    2
    3
    4
    5
    6
    7
    
           import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    response = client.numbers.delete(
        number='17609915566', )
    print(response)
           
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
           require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.numbers.delete(
        '17609915566'
      )
      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.unrent(
            "17609915566", // 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
    16
    17
    
           <?php
    
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("<auth_id>","<auth_token>");
    
    try {
        $response = $client->numbers->delete(
            '17609915566'
        );
        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.number;
    
    import java.io.IOException;
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.number.Number;
    
    
    class NumberDelete {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                Number.deleter("17609915566")
                    .delete();
    
                System.out.println("Deleted successfully.");
            } 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
    
           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.Number.Delete(
                        number:"17609915566"
                    );
                    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
    
           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
    		}
    	err = client.Numbers.Delete(
    		"17609915566",
    	)
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Println("Deleted successfully.")
    }
           
    
    1
    2
    3
    
           curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
        https://api.plivo.com/v1/Account/{auth_id}/Number/1111111111/
           
    

    Next Step

    Learn how to Search and Rent Phone Numbers.