Number Pools

Number Pools API

Download OpenAPI Specification

Pools

Pool management

Available Operations

List all pools

Return all of the pools available on an account

gethttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

Query Parameters

page_size

integer

example10

Number of objects to return on page

page

integer

Min1

example2

Page to offset the result to

Responses
Content Type
application/json

List of pools that are available

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

pools

array

fallback

string

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

examplepool_name

ID assigned to a pool of numbers

account_id

string

exampleabcd1234

Account ID to work against

_links

object

self

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id

Link to the current pool

numbers

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id/numbers

Link to the numbers in the pool

_links

object

self

object

href

string

example/v2/numberpools?page=3

Link to the current page

object

href

string

example/v2/numberpools?page=4

Link to the next available page

object

href

string

example/v2/numberpools?page=2

Link to the previous available page

first

object

href

string

example/v2/numberpools?page=1

Link to the first available page

last

object

href

string

example/v2/numberpools?page=10

Link to the last available page

Example Response

{
   "page_size": 10,
   "page": 2,
   "total_pages": 100,
   "total_items": 100,
   "_embedded": {
      "pools": [
         {
            "fallback": "Pool",
            "localized_sender_preferred": true,
            "predictable_sender_preferred": true,
            "pool_id": "pool_name",
            "account_id": "abcd1234",
            "_links": {
               "self": {
                  "href": "/v2/numberpools/abcd123/custom_user_pool_id"
               },
               "numbers": {
                  "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
               }
            }
         }
      ]
   },
   "_links": {
      "self": {
         "href": "/v2/numberpools?page=3"
      },
      "next": {
         "href": "/v2/numberpools?page=4"
      },
      "previous": {
         "href": "/v2/numberpools?page=2"
      },
      "first": {
         "href": "/v2/numberpools?page=1"
      },
      "last": {
         "href": "/v2/numberpools?page=10"
      }
   }
}

Create a new pool of numbers

Create a pool that will contain a list of numbers to send or call from

posthttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

Request Body
Content Type
application/json

fallback

string

Required

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

Required

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

Required

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

Required

examplepool_name

ID assigned to a pool of numbers

Example Request

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name"
}

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name"
}

Responses
Content Type
application/json

Information about a specific pool

fallback

string

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

examplepool_name

ID assigned to a pool of numbers

account_id

string

exampleabcd1234

Account ID to work against

_links

object

self

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id

Link to the current pool

numbers

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id/numbers

Link to the numbers in the pool

Example Response

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name",
   "account_id": "abcd1234",
   "_links": {
      "self": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id"
      },
      "numbers": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
      }
   }
}

Get information about a specific pool

gethttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

Responses
Content Type
application/json

Information about a specific pool

fallback

string

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

examplepool_name

ID assigned to a pool of numbers

account_id

string

exampleabcd1234

Account ID to work against

_links

object

self

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id

Link to the current pool

numbers

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id/numbers

Link to the numbers in the pool

Example Response

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name",
   "account_id": "abcd1234",
   "_links": {
      "self": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id"
      },
      "numbers": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
      }
   }
}

Update part of a number pool

Update an existing pool with new information without requiring all information

patchhttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

Request Body
Content Type
application/json

fallback

string

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

examplepool_name

ID assigned to a pool of numbers

Example Request

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name"
}

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name"
}

Responses
Content Type
application/json

Information about a specific pool

fallback

string

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

examplepool_name

ID assigned to a pool of numbers

account_id

string

exampleabcd1234

Account ID to work against

_links

object

self

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id

Link to the current pool

numbers

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id/numbers

Link to the numbers in the pool

Example Response

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name",
   "account_id": "abcd1234",
   "_links": {
      "self": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id"
      },
      "numbers": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
      }
   }
}

Delete a specific pool

deletehttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

Responses
Content Type
application/json

Information about a specific pool

fallback

string

examplePool

Specifies the behaviour when no number with matching prefix

Must be one of:PoolCustomFromReject

localized_sender_preferred

boolean

exampletrue

If set to true and such a number is available, select a number at random from within this pool with the same country prefix as the destination.

predictable_sender_preferred

boolean

exampletrue

When true, select the same Sender ID on any subsequent messages to a given destination.

pool_id

string

examplepool_name

ID assigned to a pool of numbers

account_id

string

exampleabcd1234

Account ID to work against

_links

object

self

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id

Link to the current pool

numbers

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id/numbers

Link to the numbers in the pool

Example Response

{
   "fallback": "Pool",
   "localized_sender_preferred": true,
   "predictable_sender_preferred": true,
   "pool_id": "pool_name",
   "account_id": "abcd1234",
   "_links": {
      "self": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id"
      },
      "numbers": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
      }
   }
}

Numbers

Manage numbers within a pool

Available Operations

Get a list of numbers inside of a specific pool

Get numbers in a pool

gethttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

Query Parameters

page_size

integer

example10

Number of objects to return on page

page

integer

Min1

example2

Page to offset the result to

Responses
Content Type
application/json

List of numbers that exist in a pool

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

numbers

array

_links

object

self

object

href

string

example/v2/numberpools/abcd123/pool_id/numbers?page=3

Link to the current page

object

href

string

example/v2/numberpools/abcd123/pool_id/numbers?page=4

Link to the next available page

object

href

string

example/v2/numberpools/abcd123/pool_id/numbers?page=2

Link to the previous available page

first

object

href

string

example/v2/numberpools/abcd123/pool_id/numbers?page=1

Link to the first available page

last

object

href

string

example/v2/numberpools/abcd123/pool_id/numbers?page=10

Link to the last available page

Example Response

{
   "page_size": 10,
   "page": 2,
   "total_pages": 100,
   "total_items": 100,
   "_embedded": {
      "numbers": [
         "15556660001",
         "15556660002"
      ]
   },
   "_links": {
      "self": {
         "href": "/v2/numberpools/abcd123/pool_id/numbers?page=3"
      },
      "next": {
         "href": "/v2/numberpools/abcd123/pool_id/numbers?page=4"
      },
      "previous": {
         "href": "/v2/numberpools/abcd123/pool_id/numbers?page=2"
      },
      "first": {
         "href": "/v2/numberpools/abcd123/pool_id/numbers?page=1"
      },
      "last": {
         "href": "/v2/numberpools/abcd123/pool_id/numbers?page=10"
      }
   }
}

Add numbers to a pool

Add a series of numbers to a pool. This endpoint supports partial successes. If a request is partially successful, the response code will be 207 and information will be returned in the body.

If all items succeed, you will receive a 200. If all items fail, you will receive a 400.

posthttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

Request Body
Content Type
application/json

numbers

array

Required

Example Request

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

Responses
Content Type
application/json

Numbers successfully added to pool

numbers

array

Numbers added to pool

_links

object

self

object

href

string

example/v2/numberpools/abcd123/custom_user_pool_id/numbers

Link back to the number pool

Example Response

{
   "numbers": [
      "15556660001"
   ],
   "_links": {
      "self": {
         "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
      }
   }
}

Remove a series of number from a pool

Remove a series of numbers from a pool. This endpoint supports partial successes. If a request is partially successful, the response code will be 207 and details can be found in the response body.

If all items succeed, you will receive a 200. If all items fail, you will receive a 400.

posthttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers/delete

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

Request Body
Content Type
application/json

numbers

array

Required

Example Request

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

Responses

No Content

Remove a specific of number from a pool

Remove a single number from a pool.

deletehttps://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers/:number

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

account_id

string

Required

exampleabcd1234

Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.

pool_id

string

Required

examplepool_name

Pool ID to work with

number

string

Required

Min7

Max15

example14155550110

Number to work with inside a pool

Responses

No Content

Number Pools

Pools

Available Operations

List all pools

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Example Response

Create a new pool of numbers

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Get information about a specific pool

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update part of a number pool

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete a specific pool

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Numbers

Available Operations

Get a list of numbers inside of a specific pool

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Example Response

Add numbers to a pool

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Remove a series of number from a pool

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses

Remove a specific of number from a pool

Authentication

Path Parameters

Responses

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json