Rest API


The IOVOX REST API can be used to white label almost all functionality found in iovox Enterprise portal.

  • Purchasing tracking numbers (VoxNumbers)

  • Setting up your tracking numbers

  • Creating advanced custom Call Flows (including IVRs and intelligent call routing)

  • Retrieving call statistics, CDRs and Recordings

  • Initiate Outbound Calls (ie. Click to Call)


There are 2 environments available for use with the IOVOX Enterprise REST v3.0 API:

  • (Sandbox) for integration and testing. Here, all purchased VoxNumbers are fake (not callable) unless otherwise stated.

    — and —

  • (Production) for your live account.

API Characteristics

Each uses its own database therefore, for security reasons a separate secure key is required for each. You can also set IP access independently on these platforms using the Settings > API Settings page in the IOVOX Enterprise portal.


The IOVOX Enterprise API requires authentication via a Username and Secure Key combination, which is tied to a single or range of IP addresses. This can be obtained by contacting and specifying the IP address(es) requests will be made from. You can manage the IP ranges which have to have access to our servers in our Portal using the "API Settings" in the Admin section.

The URL must be accessed over HTTPS on port 444 with the Username and Secure Key sent as HTTP Headers with each API call under the parameter names username and secureKey respectively.


URL: — or —

GET /Calls HTTP/1.1
username: RestUserName
secureKey: eb94fd75a6a8c04306dd341953e7e922
Error Response Format

HTTP responses return errors as XML in the following format with the HTTP status code under the attribute "status" and the error message in the node value. Multiple errors can be returned in the same response.

Specific error messages are detailed under each request description.


<?xml version="1.0" encoding="utf-8"?>

    <error status="401">HTTP 401: Unauthorized</error>
General Errors

The following details the non-method-specific error messages that may be encountered when using the API.

HTTP Code Error String Resolution
401 HTTP 401: Unauthorized Correct partner, username and secureKey combination and check IP address is registered with account. Note: sandbox and production use separate databases to store IP addresses
400 HTTPS Required Access the API using HTTPS in the URL instead of HTTP
400 Username Empty Add username to the secure headers
400 Secure Key Empty Add secureKey to the secure headers
400 Interface Name Empty Add /interfaceName to API url, e.g. /Calls to access Calls interface
400 Interface does not exist: exampleInterface Correct exampleInterface to be a valid interface for the specified version
400 Method Empty Add method=exampleMethod to URL querystring
400 Method Invalid: doesntExist in interface Calls Correct exampleMethod to a valid method for interface exampleInterface
400 API Version Empty Add v parameter to URL querystring
400 Invalid API Version Correct v parameter
500 Internal Server Error Retry later

Most Common API Integration Methods

Set up Special Accounts

Quick Start Guide

Create New Tracking Numbers

Suspend/Un-suspend Existing VoxNumbers

Delete Existing VoxNumbers

Update Call Flows (ie. change call destination)

Click to Call

Retrieve Detailed Call Data

Retrieve Call Recordings

Full Interfaces Index

Account Setup






In order to start tracking calls you will want to set up trackable items (Nodes) and specify channels or marketing streams (Links) that have unique phone numbers attached (VoxNumbers). We recognise some terminology isn't super intuitive, so here is a breakdown:


The item you want to track. For example, a customer, a business, a restaurant, a property

The way you wish to track this Node, e.g. a marketing channel. A Node can have many Links. For example, a newspaper, a website, a magazine or other campaign.

VoxNumber / iovox Number

The tracking phone number. A Link can have one tracking number which you display for people to call.


Any meta data you wish to attach to the Link. A Link has unlimited Categories. For example, if your Nodes are restaurants you may wish to add Categories that specify the type of cuisine that the restaurant provides. This way you can then generate analytics based on which drive most calls. Categories can also be used to make Call Flows more dynamic. For example you could customise a message played to the caller based on the restaurant cuisine.

Call Flow

A Call Flow is a set of rules that dictates the behaviour when someone calls one of your VoxNumbers. These can be simple such as just forwarding a call to a contact, or involve many rules that provide interactive menus, make requests out to external APIs, and much more. See the CallFlow section for more information.