Pool management
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.
Number of objects to return on page
Page to offset the result to
Items per page
Page Offset
Number of pages in the entire result set
Number of items in the entire result set
Specifies the behaviour when no number with matching prefix
One of:Pool
, CustomFrom
or Reject
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.
When true, select the same Sender ID on any subsequent messages to a given destination.
ID assigned to a pool of numbers
Account ID to work against
{
"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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Account ID to filter to. Use your Vonage API key as the value. You can see your API Key on your Vonage API Dashboard.
Specifies the behaviour when no number with matching prefix
Must be one of:Pool
, CustomFrom
or Reject
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.
When true, select the same Sender ID on any subsequent messages to a given destination.
ID assigned to a pool of numbers
Specifies the behaviour when no number with matching prefix
One of:Pool
, CustomFrom
or Reject
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.
When true, select the same Sender ID on any subsequent messages to a given destination.
ID assigned to a pool of numbers
Account ID to work against
{
"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",
"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
https://api.nexmo.com/v2/numberpools/accounts/:account_id/:pool_id
Host
https://api.nexmo.com
GET
/v2/numberpools/accounts/:account_id/:pool_id
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
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 to work with
Specifies the behaviour when no number with matching prefix
One of:Pool
, CustomFrom
or Reject
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.
When true, select the same Sender ID on any subsequent messages to a given destination.
ID assigned to a pool of numbers
Account ID to work against
{
"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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
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 to work with
Specifies the behaviour when no number with matching prefix
Must be one of:Pool
, CustomFrom
or Reject
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.
When true, select the same Sender ID on any subsequent messages to a given destination.
ID assigned to a pool of numbers
Specifies the behaviour when no number with matching prefix
One of:Pool
, CustomFrom
or Reject
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.
When true, select the same Sender ID on any subsequent messages to a given destination.
ID assigned to a pool of numbers
Account ID to work against
{
"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",
"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"
}
Manage numbers within a 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
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 to work with
Number of objects to return on page
Page to offset the result to
Items per page
Page Offset
Number of pages in the entire result set
Number of items in the entire result set
{
"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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
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 to work with
Add numbers to a number pool
Numbers added to pool
Numbers added to pool
Link to error / remediation options
Generic error message
Additional information about the error
Instance ID
{
"numbers": [
"15556660001",
"15556660002"
]
}
{
"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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
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 to work with
Add numbers to a number pool
Link to error / remediation options
Generic error message
Additional information about the error
Instance ID
Generic error message
Link to error / remediation options
Additional information about the error
{
"numbers": [
"15556660001",
"15556660002"
]
}
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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Number to work with inside a pool
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 to work with
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"
}