Buy a Phone Number

    Buys the phone number and adds it to your account. Certain countries have address and identity verification requirements. Phone numbers bought from these countries are activated after the provision of the required verification documents.

    API Endpoint

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

    Arguments

    app_id string

    The application to be assigned to the phone number. If not specified, the application selected as the default_number_app of the Account is assigned. For more information, refer default_number_app argument in application and app_id attribute in application object.

    Response

    HTTP Status Code: 201

    {
        "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
        "message": "created",
        "numbers": [
            {
                "number": "14154009186",
                "status": "Success"
            }
        ],
        "status": "fulfilled"
    }
    

    For countries which verification requirements, an email is sent to the registered email with the requirements and you will receive the below response.

    {
        "api_id": "aa52882c-1c88-11e4-bd8a-12313f016a39",
        "message": "created",
        "numbers": [
            {
                "number": "4969365065273",
                "status": "pending"
            }
        ],
        "status": "fulfilled"
    }
    

    Example Request

    1
    2
    3
    4
    5
    
    import plivo
    
    client = plivo.RestClient()
    response = client.numbers.buy(number='441273257545')
    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 Create
    #
    require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN")
    
    begin
      response = api.phonenumbers.buy(
        '10123456789',
        'app id to link with'
      )
      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 create
    
    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.buy(
            "10123456789", // 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
    18
    
    <?php
    /**
     * Example for PhoneNumber create
     */
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");
    
    try {
        $response = $client->phonenumbers->buy(
            '10123456789'
        );
        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.number.PhoneNumberCreateResponse;
    
    /**
    * Example for PhoneNumber create
    */
    class PhoneNumberCreate {
        public static void main(String [] args) {
            Plivo.init();
            try {
                PhoneNumberCreateResponse response = PhoneNumber.creator("10123456789")
                    .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
    26
    27
    28
    29
    
    /**
     * Example for PhoneNumber Create
     */
    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.Buy(
                        number:"10123456789"
                    );
                    Console.WriteLine(response);
                }
                catch (PlivoRestException e)
                {
                    Console.WriteLine("Exception: " + e.Message);
                }
            }
        }
    }
    
    1
    2
    3
    
    curl -X POST -i --user AUTH_ID:AUTH_TOKEN 
        -H "Content-Type: application/json"  
        https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/444444444444/
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    // Example for PhoneNumber create
    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.Create(
    		"123", 
    		plivo.PhoneNumberCreateParams{},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }