Get Started with Phone Numbers

These actions can be performed with the Phone Number API:

Search for New Numbers
Rent a Number

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

Prerequisites

Sign up for a free Plivo trial account.
Check out our server SDKs and install the SDK for the programming language you want to use.
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.
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 Phone Number 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
20
21
22
23
24
25
       package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.PhoneNumbers.List(
		plivo.PhoneNumberListParams{CountryISO: "GB"},
	)
	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}/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
21
22
23
24
25
26
       package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.PhoneNumbers.Create(
		"441273257545",
		plivo.PhoneNumberCreateParams{},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	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.

Rate this page

🥳 Thank you! It means a lot to us!