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

string

Unique identifier for the number pool.

string

Subresource URI for numbers in the pool.

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:

string

Unique identifier for the number pool.

string

The phone number.

string

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

string

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

string

The ISO2 code of the country associated with the number.

string

Timestamp in ISO 8601 format.

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

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

string

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

string

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

string

Filter by capability: sms or mms.

string

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

integer

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

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

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:

string

Unique identifier for the number pool.

string

The shortcode value.

string

ISO2 code of the country associated with the shortcode.

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:

string

Unique identifier for the number pool.

string

The toll-free number.

string

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

string

The service capability: sms or mms.

string

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

string

Timestamp in ISO 8601 format.

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

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"
}