This functionality uses a new REST endpoint

To access the features references on this page please ensure that you are using the REST endpoints defined on this page

Introduction¶

Dynamic Rotating Numbers enable you to allocate numbers on demand, and dynamically forward them to a destination phone provided in real-time. Numbers are pulled from a pool, and you may configure multiple number pools for different scenarios such areas, lead type, web-pages, etc. Dynamic number insertion via our JavaScript snippet is used to display the numbers in these pools on your website, once the pools are configured check the JavaScript documentation on how to use this snippet to insert numbers into your web pages.

Using the API endpoints below you can manage the pools and the numbers allocated to these pools.

REST endpoints¶

The number pools functionality is part of our new platform and as such uses different REST endpoints to our enterprise API, all functionality described on this page can only be access via the endpoints described below.  You may be required to integrate with both our traditional enterprise API and the new REST API, for example purchasing numbers is on the traditional API, while assigning those purchased numbers to a pool is done via the new REST API.

While developing your integration please ensure that you use Sandbox, this environment will incur no additional costs and setup specifically to allow customers a playground to test out their integration before going live.

Authentication¶

The method of authentication remains the same and is common across both API endpoints, below is an example cURL request to create a pool with only the authentication headers, these same headers must be present on all requests to this endpoint.

NOTE: The authentication is not the same as what is used for the JavaScript API (accessKey), these are different to ensure full API is not part of the JavaScript snippet.  This API uses the secureKey.

curl -L -X POST 'https://sandbox-rest.iovox.com/rest/v1/numbers/pool' -H 'username: CUSTOMER\_USERNAME' -H 'secureKey: API\_SECURE\_KEY'

Requests/Responses¶

All requests and responses are in JSON, when performing a POST or PUT request the request body must be valid JSON.  When performing a POST/PUT request it is possible for the REST endpoint not to return a response and the HTTP response code must be used to ensure that the request was successful.

This documentation will show the request body and the responses to each endpoint, but won't include the whole request including headers for compactness, below is a full example of a cURL requests that might be used.

curl -L -X POST 'http://sandbox-rest.iovox.com/rest/v1/numbers/pool' \
-H 'username: CUSTOMER\_USERNAME' \
-H 'secureKey: API\_SECURE\_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"pool_id": "1234", "site_url": "example.com", "template_name": "Call Me", "numbers": ["14240000000", "14240000001", "14240000003"]}'

Validation errors¶

In the event that a request contains invalid or required fields are missing or in the wrong format, a response will be generated that contains the list of errors similar to the one below.

{
  "errors": [
    "template_name needs to be an existing call template",
    "numbers needs to be an array of numbers that already exist in your account and be unassigned"
  ]
}

Methods¶

This is a list of all paths and methods that are available to manage number pools

Pools¶

Pool fields¶

When creating or updating pools the following fields are available.

Create a number pool¶

Before numbers can be assigned to a pool, first you need to create it.  This is simply a matter performing a POST to /rest/v1/numbers/pool, you can optionally specify the numbers to assign to the pool at create time or you can assign them later using the assign endpoint below.  If you wish to assign numbers at pool creation, you need to ensure that you have purchased the numbers already, not assigned to another pool and not assigned to a node or link.

POST /rest/v1/numbers/pool
{
  "pool_id": "abc123",
  "site_url": "www.example.com",
  "template_name": "Call Liverpool Office",
  "dial_string": "4420",
  "link_id": "liverpool_main",
  "numbers": [
    "442080000000",
    "442080000001",
    "442080000002"
  ]
}

If the pool is successfully created the endpoint will return a HTTP 201 response.

Retrieve pool details¶

Once a pool has been configured you can use  GET request to retrieve the pool details by looking it up by its pool_id.

GET /rest/v1/numbers/pool/abc123

The response will include all fields including the default values if applicable.

{
  "pool_id": "abc123",
  "site_url": "www.example.com",
  "dial_string": "4420",
  "pool_empty_action": "CONTINUE",
  "lifetime_minutes": 10080,
  "template_name": "Call Liverpool Office",
  "link_id": "liverpool_main",
  "link_name": "Liverpool main office number",
  "numbers": [
    "442080000000",
    "442080000001",
    "442080000002"
  ]
}

Retrieve all pools¶

Once at least one pool has been configured you can use  GET request to retrieve all pools details

GET /rest/v1/numbers/pool

The response will include all fields of retreive pool details for all available pools.

[
 {
  "pool_id": "abc123",
  "site_url": "www.example.com",
  "dial_string": "4420",
  "pool_empty_action": "CONTINUE",
  "lifetime_minutes": 10080,
  "template_name": "Call Liverpool Office",
  "link_id": "liverpool_main",
  "link_name": "Liverpool main office number",
  "numbers": [
    "442080000000",
    "442080000001",
    "442080000002"
  ]
 },
 {
  "pool_id": "test123",
  "site_url": "www.example2.com",
  "dial_string": "4430",
  "pool_empty_action": "CONTINUE",
  "lifetime_minutes": 10080,
  "template_name": "Call Manchester Office",
  "link_id": "manchester_main",
  "link_name": "Liverpool main office number",
  "numbers": [
    "443080000000",
    "443080000001",
    "443080000002"
  ]
 },
 ...
]

Updating pool details¶

Updating the settings on a pool is very similar to creating a pool, except using a PUT request.  You can change all details of the pool including the pool_id

Note: You cannot change the numbers assigned to a pool in an update, you must use the number assign/remove methods below.

PUT /rest/v1/numbers/pool/abc123
{
  "pool_id": "hiumnovegwcrmnhiou",
  "site_url": "www.example.co.uk",
  "template_name": "Call Me Maybe",
  "dial_string": 4401092,
  "pool_empty_action":"ERROR",
  "lifetime_minutes":180,
  "link_id": "manchester_main"
}

If the pool is successfully updated the endpoint will return a HTTP 204 response.

Deleting a pool¶

When a pool is deleted the numbers remain in your account and are available to be reassigned or used on any of our products.  If you no longer wish to be charged for these numbers you will need to either delete the numbers via the web portal or via the traditional API.

DELETE /rest/v1/numbers/pool/hiumnovegwcrmnhio

Number management¶

Once a pool has been created numbers can be added and removed as required.  When adding numbers the numbers need to already be in your account, not assigned to another pool and not assigned to a node/link.

Note: When numbers are removed from a pool they remain in your account and are available to be reassigned or used on any of our products.  If you no longer wish to be charged for these numbers you will need to either delete the numbers via the web portal or via the traditional API.

Assign number(s) to pool¶

To add numbers to a pool simply pass a JSON array of numbers you wish to add to the pool.

PUT /rest/v1/numbers/pool/assign/abc123
[
  "440192000000"
]

If the numbers are successfully added to the pool the endpoint will return a HTTP 204 response.

Delete number(s) from pool¶

To remove numbers from a pool simply pass a JSON array of numbers you wish to remove.

DELETE /rest/v1/numbers/pool/assign/abc123
[
  "440192000000"
]

If the numbers have been successfully removed from the pool the endpoint will return a HTTP 204 response.