Skip to navigation
Pools Numbers


Endpoints

Pools Numbers
 
 

Number Pools

Number Pools API

Download OAS 3 Definition
Improve this specification

Jump to:

Pools »

Pool management

Numbers »

Manage numbers within a pool

Pools

Pool management

Available Operations:

List all pools

Return all of the pools available on an account

GET https://api.nexmo.com/v2/numberpools/accounts/:account_id/pools
Host https://api.nexmo.com
GET /v2/numberpools/accounts/:account_id/pools

Authentication

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

Path Parameters

account_id
string | Required

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 Parameter

page_size
integer

Number of objects to return on page

page
integer

Page to offset the result to

Responses

200 List of pools that are available
page_size
integer

Items per page

page
integer

Page Offset

total_pages
integer

Number of pages in the entire result set

total_items
integer

Number of items in the entire result set

_embedded
object
pools
array
fallback
string

Specifies the behaviour when no number with matching prefix

One of: Pool, CustomFrom or Reject
localized_sender_preferred
boolean

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

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

pool_id
string

ID assigned to a pool of numbers

account_id
string

Account ID to work against

Example Responses

200 401 404 
{
  "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"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Create a new pool of numbers

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

POST https://api.nexmo.com/v2/numberpools/accounts/:account_id/pools
Host https://api.nexmo.com
POST /v2/numberpools/accounts/:account_id/pools

Authentication

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

Path Parameters

account_id
string | Required

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 application/json

fallback
string | Required

Specifies the behaviour when no number with matching prefix

Must be one of: Pool, CustomFrom or Reject
localized_sender_preferred
boolean | Required

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

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

pool_id
string | Required

ID assigned to a pool of numbers

Responses

201 Information about a specific pool
fallback
string

Specifies the behaviour when no number with matching prefix

One of: Pool, CustomFrom or Reject
localized_sender_preferred
boolean

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

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

pool_id
string

ID assigned to a pool of numbers

account_id
string

Account ID to work against

Example Request

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

Example Responses

201 400 401 404 409 
{
  "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"
    }
  }
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "name": "abc123",
      "reason": "abc123"
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#invalid-json",
  "title": "Unable to parse incoming request",
  "detail": "invalid character 'f' after object key:value pair",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#pool-id-exists",
  "title": "Pool ID already exists",
  "detail": "A pool with the specified ID already exists",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Get information about a specific pool

Get information about a specific pool

GET https://api.nexmo.com/v2/numberpools/accounts/:account_id/:pool_id
Host https://api.nexmo.com
GET /v2/numberpools/accounts/:account_id/:pool_id

Authentication

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

Path Parameters

account_id
string | Required

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

Pool ID to work with

Responses

200 Information about a specific pool
fallback
string

Specifies the behaviour when no number with matching prefix

One of: Pool, CustomFrom or Reject
localized_sender_preferred
boolean

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

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

pool_id
string

ID assigned to a pool of numbers

account_id
string

Account ID to work against

Example Responses

200 401 404 
{
  "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"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Update part of a number pool

Update an existing pool with new information without requiring all information

PATCH https://api.nexmo.com/v2/numberpools/accounts/:account_id/:pool_id
Host https://api.nexmo.com
PATCH /v2/numberpools/accounts/:account_id/:pool_id

Authentication

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

Path Parameters

account_id
string | Required

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

Pool ID to work with

Request body application/json

fallback
string

Specifies the behaviour when no number with matching prefix

Must be one of: Pool, CustomFrom or Reject
localized_sender_preferred
boolean

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

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

pool_id
string

ID assigned to a pool of numbers

Responses

201 Information about a specific pool
fallback
string

Specifies the behaviour when no number with matching prefix

One of: Pool, CustomFrom or Reject
localized_sender_preferred
boolean

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

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

pool_id
string

ID assigned to a pool of numbers

account_id
string

Account ID to work against

Example Request

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

Example Responses

201 400 401 404 409 
{
  "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"
    }
  }
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": {
    "name": "localized_sender_preferred",
    "reason": "Must be a boolean value"
  }
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#invalid-json",
  "title": "Unable to parse incoming request",
  "detail": "invalid character 'f' after object key:value pair",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#account-id-mismatch",
  "title": "The Account ID does not match the original Account ID",
  "detail": "When updating a number pool, the account ID is read-only and cannot change",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Numbers

Manage numbers within a pool

Available Operations:

Get a list of numbers inside of a specific pool

Get numbers in a pool

GET https://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers
Host https://api.nexmo.com
GET /v2/numberpools/accounts/:account_id/pools/:pool_id/numbers

Authentication

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

Path Parameters

account_id
string | Required

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

Pool ID to work with

Query Parameter

page_size
integer

Number of objects to return on page

page
integer

Page to offset the result to

Responses

200 List of numbers that exist in a pool
page_size
integer

Items per page

page
integer

Page Offset

total_pages
integer

Number of pages in the entire result set

total_items
integer

Number of items in the entire result set

_embedded
object
numbers
array of strings

Example Responses

200 401 404 
{
  "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"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

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.

POST https://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers
Host https://api.nexmo.com
POST /v2/numberpools/accounts/:account_id/pools/:pool_id/numbers

Authentication

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

Path Parameters

account_id
string | Required

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

Pool ID to work with

Request body application/json

numbers
array of strings | Required

Add numbers to a number pool

Responses

201 Numbers successfully added to pool
numbers
array of strings

Numbers added to pool

207 Only part of a number list was added to a pool
numbers
array of strings

Numbers added to pool

error
type
string

Link to error / remediation options

title
string

Generic error message

detail
string

Additional information about the error

instance
string

Instance ID

errors
array

Example Request

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

Example Responses

201 207 400 401 404 
{
  "numbers": [
    "15556660001"
  ],
  "_links": {
    "self": {
      "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
    }
  }
}
{
  "numbers": [
    "15556660001"
  ],
  "_links": {
    "self": {
      "href": "/v2/numberpools/abcd123/custom_user_pool_id/numbers"
    }
  },
  "error": {
    "type": "https://developer.nexmo.com/api-errors/number-pools#add-numbers-partial-failure",
    "title": "Could not add all numbers to pool",
    "detail": "One or more numbers encountered issues being added to the pool",
    "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
    "errors": [
      {
        "type": "https://developer.nexmo.com/api-errors/number-pools#missing-number-subscription",
        "title": "No such number subscription",
        "detail": "One or more numbers being added are not subscribed to on this account",
        "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
        "numbers": [
          "15556660001"
        ]
      }
    ]
  }
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#add-number-failure",
  "title": "Numbers could not be added to the pool",
  "detail": "None of the numbers could be added the pool",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "errors": [
    {
      "type": "https://developer.nexmo.com/api-errors/number-pools#missing-number-subscription",
      "title": "No such number subscription",
      "detail": "One or more numbers being added are not subscribed to on this account",
      "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
      "numbers": [
        "15556660001"
      ]
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#bulk-number-delete-limit",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "name": "ids",
      "reason": "Limit of 50 numbers exceeded"
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#invalid-json",
  "title": "Unable to parse incoming request",
  "detail": "invalid character 'f' after object key:value pair",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

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.

POST https://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers/delete
Host https://api.nexmo.com
POST /v2/numberpools/accounts/:account_id/pools/:pool_id/numbers/delete

Authentication

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

Path Parameters

account_id
string | Required

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

Pool ID to work with

Request body application/json

numbers
array of strings | Required

Add numbers to a number pool

Responses

207 Error handle full or partial deletion errors
numbers
array of strings
error
type
string

Link to error / remediation options

title
string

Generic error message

detail
string

Additional information about the error

instance
string

Instance ID

errors
array of objects
error
object
title

Generic error message

type

Link to error / remediation options

detail

Additional information about the error

numbers
array of strings

Example Request

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

Example Responses

204 207 400 401 404 
No Content
{
  "numbers": [
    "15556660001",
    "15556660002"
  ],
  "error": {
    "type": "https://developer.nexmo.com/api-errors/number-pools#delete-numbers-partial-failure",
    "title": "Could not remove all numbers to pool",
    "detail": "One or more numbers encountered issues being removed from the pool",
    "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
    "errors": [
      {
        "error": {
          "title": "Number not found",
          "type": "https://developer.nexmo.com/api-errors/number-pools#missing-number",
          "detail": "One or more numbers being deleted are not available in the pool",
          "numbers": [
            "15556660001"
          ]
        }
      }
    ]
  }
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#number-deletion-failure",
  "title": "There were errors removing numbers from the pool",
  "detail": "We were unable to remove any of the numbers from the pool.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "errors": [
    {
      "title": "Number not found",
      "type": "https://developer.nexmo.com/api-errors/number-pools#missing-number",
      "detail": "One or more numbers being deleted are not available in the pool",
      "numbers": [
        "15556660001"
      ]
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#bulk-number-delete-limit",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "name": "ids",
      "reason": "Limit of 50 numbers exceeded"
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#invalid-json",
  "title": "Unable to parse incoming request",
  "detail": "invalid character 'f' after object key:value pair",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Remove a specific of number from a pool

Remove a single number from a pool.

DELETE https://api.nexmo.com/v2/numberpools/accounts/:account_id/pools/:pool_id/numbers/:number
Host https://api.nexmo.com
DELETE /v2/numberpools/accounts/:account_id/pools/:pool_id/numbers/:number

Authentication

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

Path Parameters

number
string | Required

Number to work with inside a pool

account_id
string | Required

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

Pool ID to work with

Example Responses

204 400 401 404 
No Content
{
  "type": "https://developer.nexmo.com/api-errors/number-pools#number-deletion-error",
  "title": "Could not delete number",
  "detail": "An error occurred while removing the number from the pool",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}