Number Pool - Plivo

An empty number pool resource is created automatically when a new Powerpack is created. You can add phone numbers, shortcodes, and toll-free numbers to the pool to use for messaging.

The Number Pool Object

uuid

string

Unique identifier for the number pool.

numbers

string

Subresource URI for numbers in the pool.

shortcodes

string

Subresource URI for shortcodes in the pool.

Example Object

{
    "api_id": "d7e9a038-0a88-11ea-b072-0242ac110007",
    "numbers": "/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Number/",
    "shortcodes": "/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/",
    "uuid": "{number_pool_uuid}"
}

Numbers

Numbers in a number pool have the following attributes:

number_pool_uuid

string

Unique identifier for the number pool.

number

string

The phone number.

type

string

The type of number. One of: fixed, mobile, toll-free.

service

string

The service capability of number. One of: sms, mms.

country_iso2

string

The ISO2 code of the country associated with the number.

added_on

string

Timestamp in ISO 8601 format.

account_phone_number_resource

string

Account phone number resource URI.

Example Number Object

{
    "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_number}/",
    "added_on": "2022-10-09T11:10:59.741978Z",
    "country_iso2": "US",
    "number": "{your_number}",
    "number_pool_uuid": "{number_pool_uuid}",
    "type": "fixed"
}

Add a Number

Add SMS- and MMS-enabled numbers to a number pool resource.

POST

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

Arguments

service

string

Set this parameter to sms for SMS-enabled numbers or mms for MMS-enabled numbers. Defaults to sms.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid="<powerpack_uuid>")
response = powerpack.add_number('<your_number>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.add_number('<your_number>'))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.add_number('<your_number>')
puts response

curl -X POST -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Number/{number}/

Response

{
    "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_number}/",
    "added_on": "2022-10-09T11:24:35.085797Z",
    "api_id": "612982e8-0a87-11ea-b072-0242ac110007",
    "country_iso2": "CA",
    "number": "{your_number}",
    "number_pool_uuid": "{number_pool_uuid}",
    "service": "mms",
    "type": "fixed"
}

Retrieve a Number

Retrieve the details of a specific number from a number pool.

GET

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

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid="<powerpack_uuid>")
response = powerpack.find_number('<your_number>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.find_number('<your_number>'))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.find_number('<your_number>')
puts response

curl -X GET -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Number/{number}/

Response

{
    "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_number}/",
    "added_on": "2022-10-09T11:24:35.085797Z",
    "api_id": "612982e8-0a87-11ea-b072-0242ac110007",
    "country_iso2": "CA",
    "number": "{your_number}",
    "number_pool_uuid": "{number_pool_uuid}",
    "type": "fixed"
}

List All Numbers

Fetch a list of numbers from a number pool.

GET

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

Arguments

starts_with

string

A comma-separated list of prefixes. Values provided should exclude the country code prefix. A maximum of 10 prefixes may be specified.

type

string

Filter by number type: fixed, toll-free, or mobile. Note that local and national numbers should be considered as fixed.

service

string

Filter by capability: sms or mms.

country_iso2

string

ISO2 code of the phone number country. Required if the starts_with filter is specified.

limit

integer

Number of results per page. Maximum is 20. Defaults to 20.

offset

integer

Number of value items by which the results should be offset. Defaults to 0.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid="<powerpack_uuid>")
response = powerpack.list_numbers(starts_with='512', country_iso2='US')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.list_numbers({ limit: '2', offset: '0' }))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.list_numbers(limit: 2, offset: 0)
puts response

curl -X GET -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    "https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Number/?starts_with=484&country_iso2=US"

Response

{
    "api_id": "06c15d7c-7ed5-11ea-855f-0242ac110003",
    "meta": {
        "limit": 20,
        "next": "",
        "offset": 0,
        "previous": "",
        "total_count": 2
    },
    "objects": [
        {
            "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_number}/",
            "added_on": "2023-03-18T16:07:39.379739Z",
            "country_iso2": "US",
            "number": "{your_number}",
            "number_pool_uuid": "{number_pool_uuid}",
            "service": "mms",
            "type": "fixed"
        },
        {
            "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_number}/",
            "added_on": "2022-10-09T11:24:35.085797Z",
            "country_iso2": "CA",
            "number": "{your_number}",
            "number_pool_uuid": "{number_pool_uuid}",
            "service": "sms",
            "type": "fixed"
        }
    ]
}

Remove a Number

Remove a number from a number pool.

DELETE

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

Arguments

unrent

boolean

Set to true to also unrent the number. Defaults to false.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid="<powerpack_uuid>")
response = powerpack.remove_number('<your_number>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.remove_number('<your_number>', true))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.remove_number('<your_number>', unrent: true)
puts response

curl -X DELETE -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Number/{number}/

Response

{
    "api_id": "c378d44c-0a89-11ea-b072-0242ac110007",
    "response": "success"
}

Shortcodes

Shortcodes in a number pool have the following attributes:

number_pool_uuid

string

Unique identifier for the number pool.

shortcode

string

The shortcode value.

country_iso2

string

ISO2 code of the country associated with the shortcode.

added_on

string

Timestamp in ISO 8601 format.

Example Shortcode Object

{
    "added_on": "2022-10-09T11:10:59.741978Z",
    "api_id": "b42933e8-0a88-11ea-b072-0242ac110007",
    "country_iso2": "US",
    "number_pool_uuid": "{number_pool_uuid}",
    "shortcode": "{your_shortcode}"
}

Retrieve a Shortcode

Retrieve the details of a specific shortcode from a number pool.

GET

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/{shortcode}/

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
response = powerpack.find_shortcode('<shortcode>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.find_shortcode('<shortcode>'))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.find_shortcode('<shortcode>')
puts response

curl -X GET -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/{shortcode}/

Response

{
    "added_on": "2022-10-09T11:10:59.741978Z",
    "api_id": "b42933e8-0a88-11ea-b072-0242ac110007",
    "country_iso2": "US",
    "number_pool_uuid": "{number_pool_uuid}",
    "shortcode": "{your_shortcode}"
}

List All Shortcodes

Fetch a list of shortcodes from a number pool.

GET

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
response = powerpack.list_shortcodes()
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.list_shortcodes())
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.list_shortcodes()
puts response

curl -X GET -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/

Response

{
    "api_id": "614b2776-0a88-11ea-b072-0242ac110007",
    "meta": {
        "limit": 20,
        "next": "",
        "offset": 0,
        "previous": "",
        "total_count": 1
    },
    "objects": [
        {
            "added_on": "2019-10-09T11:10:59.741978Z",
            "country_iso2": "US",
            "number_pool_uuid": "{number_pool_uuid}",
            "shortcode": "{your_shortcode}"
        }
    ]
}

Remove a Shortcode

Remove a shortcode from a number pool. Note that the shortcode is only unlinked from the number pool, not unrented.

DELETE

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/{shortcode}/

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
response = powerpack.remove_shortcode('<shortcode>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.remove_shortcode('<shortcode>'))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.remove_shortcode('<shortcode>')
puts response

curl -X DELETE -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Shortcode/{shortcode}/

Response

{
    "api_id": "c378d44c-0a89-11ea-b072-0242ac110007",
    "response": "success"
}

Toll-Free Numbers

Toll-free numbers in a number pool have the following attributes:

number_pool_uuid

string

Unique identifier for the number pool.

number

string

The toll-free number.

type

string

The type of number. Always tollfree for toll-free numbers.

service

string

The service capability: sms or mms.

country_iso2

string

ISO2 code of the country associated with the toll-free number.

added_on

string

Timestamp in ISO 8601 format.

account_phone_number_resource

string

Account phone number resource URI.

Example Toll-Free Object

{
    "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_tollfree_number}/",
    "added_on": "2021-04-15T04:49:51.228392Z",
    "api_id": "8a6bba9c-7ed4-11ea-b82e-0242ac110006",
    "country_iso2": "US",
    "number": "{your_tollfree_number}",
    "number_pool_uuid": "{number_pool_uuid}",
    "service": "mms",
    "type": "tollfree"
}

Add a Toll-Free Number

Add existing SMS- and MMS-enabled toll-free numbers to a number pool.

POST

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/{toll_free_number}/

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
response = powerpack.add_tollfree('<tollfree_number>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.add_tollfree('<tollfree_number>'))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.add_tollfree('<tollfree_number>')
puts response

curl -X POST -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/{toll_free_number}/

Response

{
    "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_tollfree_number}/",
    "added_on": "2021-04-15T04:49:51.228392Z",
    "api_id": "8a6bba9c-7ed4-11ea-b82e-0242ac110006",
    "country_iso2": "US",
    "number": "{your_tollfree_number}",
    "number_pool_uuid": "{number_pool_uuid}",
    "service": "mms",
    "type": "tollfree"
}

Retrieve a Toll-Free Number

Retrieve the details of a specific toll-free number from a number pool.

GET

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/{toll_free_number}/

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
response = powerpack.find_tollfree('<tollfree_number>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.find_tollfree('<tollfree_number>'))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.find_tollfree('<tollfree_number>')
puts response

curl -X GET -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/{toll_free_number}/

Response

{
    "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_tollfree_number}/",
    "added_on": "2023-03-18T16:07:39.379739Z",
    "api_id": "df0519d6-7ed4-11ea-b82e-0242ac110006",
    "country_iso2": "US",
    "number": "{your_tollfree_number}",
    "number_pool_uuid": "{number_pool_uuid}",
    "type": "tollfree"
}

List All Toll-Free Numbers

Fetch a list of all toll-free numbers from a number pool.

GET

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/

Arguments

No arguments need to be passed.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
response = powerpack.list_tollfree()
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    .then(powerpack => powerpack.list_tollfree())
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
response = powerpack.list_tollfree()
puts response

curl -X GET -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/

Response

{
    "api_id": "06c15d7c-7ed5-11ea-855f-0242ac110003",
    "meta": {
        "limit": 20,
        "next": "",
        "offset": 0,
        "previous": "",
        "total_count": 1
    },
    "objects": [
        {
            "account_phone_number_resource": "/v1/Account/{auth_id}/Number/{your_tollfree_number}/",
            "added_on": "2022-10-09T11:24:35.085797Z",
            "country_iso2": "US",
            "number": "{your_tollfree_number}",
            "number_pool_uuid": "{number_pool_uuid}",
            "service": "mms",
            "type": "tollfree"
        }
    ]
}

Remove a Toll-Free Number

Remove a toll-free number from a number pool.

DELETE

https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/{tollfree_number}/

Arguments

unrent

boolean

Set to true to also unrent the toll-free number. Defaults to false.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
powerpack = client.powerpacks.get(uuid='<powerpack_uuid>')
# Set second parameter to True to also unrent the number
response = powerpack.remove_tollfree('<tollfree_number>', True)
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.powerpacks.get('<powerpack_uuid>')
    // Set second parameter to true to also unrent the number
    .then(powerpack => powerpack.remove_tollfree('<tollfree_number>', true))
    .then(result => console.log(result))
    .catch(error => console.log(error));

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
powerpack = api.powerpacks.get('<powerpack_uuid>')
# Set unrent to true to also unrent the number
response = powerpack.remove_tollfree('<tollfree_number>', true)
puts response

curl -X DELETE -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    "https://api.plivo.com/v1/Account/{auth_id}/NumberPool/{number_pool_uuid}/Tollfree/{tollfree_number}/?unrent=true"

Response

{
    "api_id": "57936fb0-7ed5-11ea-aa79-0242ac110003",
    "response": "success"
}

​The Number Pool Object

​Numbers

​Add a Number

​Arguments

​Response

​Retrieve a Number

​Arguments

​Response

​List All Numbers

​Arguments

​Response

​Remove a Number

​Arguments

​Response

​Shortcodes

​Retrieve a Shortcode

​Arguments

​Response

​List All Shortcodes

​Arguments

​Response

​Remove a Shortcode

​Arguments

​Response

​Toll-Free Numbers

​Add a Toll-Free Number

​Arguments

​Response

​Retrieve a Toll-Free Number

​Arguments

​Response

​List All Toll-Free Numbers

​Arguments

​Response

​Remove a Toll-Free Number

​Arguments

​Response

The Number Pool Object

Numbers

Add a Number

Arguments

Response

Retrieve a Number

Arguments

Response

List All Numbers

Arguments

Response

Remove a Number

Arguments

Response

Shortcodes

Retrieve a Shortcode

Arguments

Response

List All Shortcodes

Arguments

Response

Remove a Shortcode

Arguments

Response

Toll-Free Numbers

Add a Toll-Free Number

Arguments

Response

Retrieve a Toll-Free Number

Arguments

Response

List All Toll-Free Numbers

Arguments

Response

Remove a Toll-Free Number

Arguments

Response