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:
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.
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 firstname.lastname@example.org 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: https://sandboxapi.iovox.com:444/ — or — https://api.iovox.com:444/
|GET /Calls HTTP/1.1|
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.
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¶
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¶
- Interface Rules
- Interface SoundFiles
- Interface Calling
- Interface CallFlow
- Interface SMS
- Interface Conversations
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.
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.