Rest API¶

Introduction¶

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)

Environments¶

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

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

— and —

api.iovox.com (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.

Authentication

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 api@iovox.com 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.

Example:

URL: https://sandboxapi.iovox.com:444/ — or — https://api.iovox.com:444/

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.

Example:¶

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

<errors>
    <error status="401">HTTP 401: Unauthorized</error>
</errors>

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¶

purchaseVoxNumbers purchases new iovox numbers (tracking numbers)
createNodeFull create all required tracking and forwarding data in one request
updateContacts update all data pertaining to a contact
deleteVoxnumbersFromAccount or removeVoxnumberFromLink when you're done using a tracking number
getCallData or getCallMetrics get the call data in raw format, or aggregated for displaying analytics

Set up Special Accounts¶

Set up Quarantine Management Process

Quick Start Guide¶

Create New Tracking Numbers¶

Suspend/Un-suspend Existing VoxNumbers¶

setCallStatus

Delete Existing VoxNumbers¶

Update Call Flows (ie. change call destination)¶

Click to Call¶

initiateCall

Retrieve Detailed Call Data¶

Retrieve Call Recordings¶

Full Interfaces Index¶

Account Setup¶

Calling¶

Numbering¶

Analytics¶

Interface Calls

Glossary/Terminology¶

Terminology

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:

Node¶

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

Link¶

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.

Category¶

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.