Buy a Phone Number

    Buys a phone number and adds it to your account. If the number is for a country that requires address and identity verification, you must provide verification documents before we can activate the phone number.

    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 to the default_number_app argument under Application and app_id attribute in the Application object.

    Response

    HTTP Status Code: 201

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

    If the number is for a country with verification requirements, Plivo sends an email message to the registered email address for the account that describes the requirements, and returns this 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('<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
    16
    17
    18
    19
    20
    
    #
    # Example for PhoneNumber Create
    #
    require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<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';
        
       // 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(
            "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("<auth_id>","<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("<auth_id>","<auth_token>");
            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("<auth_id>","<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("<auth_id>","<auth_token>", &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)
    }