VoiceMeUp XML Engine API Developer Guide
Table of Contents
Introduction

With the XML Engine API, you can interact with many VoiceMeUp services and features using simple HTTP requests, so you can easily integrate those services and features into your applications and other APIs. To use the API, you need to sign up for an API authentication key, and then follow the instructions below.

The API is not always up to date with newest features offered through the client control panel. If you would like a new feature to be implemented in the API do not hesitate to send us your requests, comments and suggestions.

Getting Started
Understanding HTTP Requests

The XML Engine API is an information exchange service that you can interact with by doing simple HTTP Requests. Every command that you wish to send to either submit information or retreive

Initial query parameters

The XML Engine API requires initial query parameter for any of the request types.

Parameter Type [?] Requirement Description
client_account_id digits[8] Required Value must be a valid `client_account_id` of 8 digits.
auth_token hex[32] Required Value must be a valid `auth_token` of 32 hexadecimal characters.
request_type string Required Value must be a valid `request_type`.
List of available request types is available here.
language string Optional Value must be one of the following : "en" or "fr".
(default en)
currency string Optional Value must be one of the following : "CAD", "USD" or "EUR".
(default CAD)
Additional parameters types

Each request types can accept different optional or required parameters. Those parameters will be validated according to the request type made.

Here is a list of definition of the different parameters types interpreted by the XML Engine API:

HTTP Query syntax

As mentioned earlier, the requests are made using plain HTTP queries. Building a query requires to Encode URL because some values might contain characters that could conflict with the query string syntax.

https://developer.voicemeup.com/xml_engine/xml_engine.php?client_account_id=80012345&auth_token=4d695127fbeedd39d423b5f9c47eabcd ...
Response format

Responses are only formatted in XML for the moment.

Show Sample XML response
Request Types
Get call history

One of the most important and practical feature is the call history which allows you to get call details as soon as it is available in our databases.

If you wish to query the XML Engine on a regular basis in order to always have an updated version, it is possible to request calls that has been logged after the last request you made by using the `unique_id`parameter.

Request Type: get_calls

Parameter Type [?] Requirement Description
date_from date Optionally Required If set, date_to must also be set.
Value must be a valid date formatted as "YYYY-MM-DD".
date_to date Optionally Required If set, date_from must also be set.
Value must be a valid date formatted as "YYYY-MM-DD".
unique_id string Optionally Required Value must be a 32 characters alphanumeric unique id referencing the last call previously returned by your last request made with `get_calls`.
direction string Optional Value must be one of the following: "inbound" or "outbound"
(default is NULL)
result_limit integer Optional Value must be between 1 and 1000
(default is 25 with date_to and date_from setted, 1 with unique_id setted)
result_offset integer Optional Value must be a valid number
(default is NULL)
metadata string Optional Value must be one of the following: "yes", "only", "all" or "no"
(default is no)
use_archive bool Optional Value must be one of the following: "1" or "0"
(default is 0). This will browse the archive.
get_routing_details bool Optional Value must be one of the following: "1" or "0"
(default is 0). This will return more details about the source and destination.
Show Sample XML response
Get recorded calls

If you have enabled recording on one of your Peer, on one of you DID or if you've made calls using the "call_dispatch" request, your calls will generate a new entry in the call recording database and you will be able to retrieve it using this request type.

Note: The "Call record" feature is only supported through the XML Engine API for now.

Request Type: get_recordings

Parameter Type [?] Requirement Description
call_recording_id integer Optional Value must be a valid `call_recording_id`.
(default is NULL)
recording_hash alphanum [36] Optional NEW : Value must be a 36 characters alphanumeric with dashes unique id referencing to a recording previously returned by a request made with `get_recordings`.
(default is NULL)
call_hash alphanum [32] Optional Value must be a 32 characters alphanumeric unique id referencing to a call previously returned by a request made with `get_calls`.
(default is NULL)
status enum Optional Value must be one (or more, comma separated) of the following: "unverified", "verified" or "deleted"
(default is NULL)
Show Sample XML response
Delete recorded calls

You can delete recordings assigned to your account either by specifying a valid `call_recording_id `or `call_hash`. Optionally you can omit those and specify a valid `date` and delete all of your recordings before that date.

Request Type: delete_recordings

Request Type Added on June 3rd 2010
Parameter Type [?] Requirement Description
call_recording_id integer Optionally required Value must be a valid `call_recording_id`. Comma separated values are accepted.
(default is NULL)
call_hash alphanum [32] Optionally required Value must be a 32 characters alphanumeric unique id referencing to a call previously returned by a request made with `get_calls`. Comma separated values are accepted.
(default is NULL)
date date Optionally required If set and no other parameter is sent, will delete all recordings prior to that date.
(default is NULL)
comments string Optional  
Show Sample XML response
Get voicemails

If you have enabled a mailbox on one of you DID, you will be able to retrieve the messages by using this request type.

Request Type: get_voicemails

Request Type Added on March 8th 2012
Parameter Type [?] Requirement Description
call_voicemail_id integer Optional Value must be a valid `call_voicemail_id`.
(default is NULL)
voicemail_hash alphanum [32] Optional Value must be a 32 characters alphanumeric with dashes unique id referencing to a voicemail previously returned by a request made with `get_voicemails`.
(default is NULL)
result_limit integer Optional Value must be between 1 and 1000
(default is 25)
result_offset integer Optional Value must be a valid number
(default is NULL)
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
date_to date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Show Sample XML response
Delete voicemails

You can delete voicemails assigned to your account either by specifying a valid `call_voicemail_id` or `voicemail_hash` . Optionally you can omit those and specify a valid `date` and delete all of your voicemails before that date.

Request Type: delete_voicemails

Request Type Added on March 8th 2012
Parameter Type [?] Requirement Description
call_voicemail_id integer Optionally required Value must be a valid `call_voicemail_id`. Comma separated values are accepted.
(default is NULL)
voicemail_hash alphanum [32] Optional Value must be a 32 characters alphanumeric with dashes unique id referencing to a voicemail previously returned by a request made with `get_voicemails`. Comma separated values are accepted.
(default is NULL)
date date Optionally required If set and no other parameter is sent, will delete all voicemails prior to that date.
(default is NULL)
comments string Optional  
Show Sample XML response
Get faxes

If you have eanbled faxes on one of your Peers, your faxes will generate a new entry in the faxes database and you will be able to retrieve it using this request type.

Request Type: get_faxes
Request Type Added on June 3rd 2010

Parameter Type [?] Requirement Description
call_fax_id integer Optional Value must be a valid `call_fax_id`.
(default is NULL)
call_hash alphanum [32] Optional Value must be a 32 characters alphanumeric unique id referencing to a call previously returned by a request made with `get_calls`.
(default is NULL)
status enum Optional Value must be one (or more, comma separated) of the following: "enabled", "deleted", "purged"
(default is NULL)
transmission_status enum Optional Value must be one (or more, comma separated) of the following: "pending", "processing", "completed", "failed", "cancelled", "paused"
(default is NULL)
Show Sample XML response
Delete stored faxes

You can delete your faxes assigned to your account either by specifying a valid `call_fax_id ` or `call_hash`. Optionally you can omit those and specify a valid `date` and delete all of your faxes for that date.

Request Type: delete_faxes

Request Type Added on June 3rd 2010
Parameter Type [?] Requirement Description
call_fax_id integer Optionally required Value must be a valid `call_fax_id`. Comma separated values are accepted.
(default is NULL)
call_hash alphanum [32] Optionally required Value must be a 32 characters alphanumeric unique id referencing to a call previously returned by a request made with `get_calls`. Comma separated values are accepted.
(default is NULL)
date date Optionally required If set and no other parameter is sent, will delete all faxes for that date.
(default is NULL)
comments string Optional  
Show Sample XML response
Get Fax profiles

If you wish to get details of a fax profiles, you simply have to pass the `client_fax_profile_id`. If no additional parameter is specified, the complete list of fax profiles will be returned.

Request Type: get_fax_profiles

Parameter Type [?] Requirement Description
client_fax_profile_id integer Optional Value must be a valid `client_fax_profile_id`.
(default is NULL)
Show Sample XML response
Queue Fax

You can send a fax with this request type. It is important to note that this is a POST request.

Request Type: queue_fax

Parameter Type [?] Requirement Description
destination_number string Required Value must be a valid phone number.
client_fax_profile_id integer Required Value must be a valid `client_fax_profile_id`.
attachments file Required Value must be valid files.
unique_id string Optional Value must be alphanumeric string. It will be used as a seed with `client_fax_profile_id`. Must be unique.
(Default is time)
name_from string Optional Value must be alphanumeric string.
(Default is fax profile contact name)
email_from string Optional Value must be alphanumeric string.
(Default is fax profile contact email)
resolution string Optional Value must be one of the following : 'standard', 'fine', 'super_fine', 'ultra_fine'.
(Default is fax profile resolution)
retry_limit string Optional Value must between 1 and 9.
(Default is fax profile retry limit)
datetime_scheduled datetime Optional Value must be a valid datetime (YYYY-MM-DD HH:II:SS).
Show Sample XML response
Get DIDs details

You can get the details and settings of DIDs assigned to your account by either specifying the `client_did_id` or the `phone_number`. If you do not provide either value, the details for all DIDs will be returned.

Request Type: get_dids

Parameter Type [?] Requirement Description
client_did_id integer Optional Value must be a valid `client_did_id`.
(default is NULL)
phone_number integer Optional Value must be a valid phone number of 10 digits.
(default is NULL)
Show Sample XML response
Update DID

It is possible to update the DIDs configuration with this request type.

Note: Not all the option for DIDs are available through the API. Please request any new feature to our support department.

Request Type: update_did

Parameter Type [?] Requirement Description
client_did_id
integer Optionally
required
Value must be a valid `client_did_id`
phone_number digits [10] Optionally required Value must be a valid DID number.
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
enable_forwarding integer Deprecated(Optional) 1 = enabled, 0 = disabled; use options instead.
(default is 0)
forward_number integer Optional Value must be a valid phone number.
(default is NULL)
forward_timeout string Optional Value must be one of the following : "disabled", "2", "5", "10", "15", "20", "25",
"30", "35", "40", "45", "50" or "55".
(default is NULL)
enable_voicemail integer Deprecated(Optional) 1 = enabled, 0 = disabled; use options instead.
(default is 0)
client_mailbox_id integer Optional Value must be a valid `client_mailbox_id`.
(default is NULL)
client_ivr_profile_id integer Optional Value must be a valid `client_ivr_profile_id`.
(default is NULL)
client_fax_profile_id integer Optional Value must be a valid `client_fax_profile_id`.
(default is NULL)
client_director_profile_id integer Optional Value must be a valid `client_director_profile_id`.
(default is NULL)
enable_peer integer Deprecated(Optional) 1 = enabled, 0 = disabled; use options instead.
(default is 0)
client_peer_ids enum Optional Value(s) must be valid client_peer_id(s) (comma separated).
(default is NULL)
peer_timeout string Optional Value must be one of the following : "disabled", "2", "5", "10", "15", "20", "25", "30", "35", "40", "45", "50" or "55".
(default is NULL)
enable_recording integer Deprecated(Optional) 1 = enabled, 0 = disabled; use options instead.
(default is 0)
ondemand_recording integer Optional 1 = enabled, 0 = disabled
(default is 0)
dnis_rewrite digits [10] Optional Value must be a valid DID number.
client_filter_ids Array Optional Value must be one or more valid client_filter_id.
(default is NULL)
options Array Optional Value must be one or more of the following : "enable_forwarding", "enable_voicemail", "enable_peer", "ondemand_recording", "enable_recording", "enable_ivr", "enable_fax".
(default is NULL)
comments string Optional  
status enum Optional Value must be one of the following: "enabled" or "disabled"
Get list of new DIDs

If you wish to get a list of DIDs in our inventory, you may request it with one of the following parameter.

Request Type: get_new_dids

Parameter Type [?] Requirement Description
type string Optional Value must be one of the following : "local", "tollfree", "inum", "international".
(default is NULL)
npa digits [3] Optional Value must be a 3 digits NPA area code. (only for local)
(default is NULL)
nxx digits [3] Optional Value must be a 3 digits NXX prefix. (only for local)
(default is NULL)
ratecenter_id digits[6] Optional Value must be a 6 digits ratecenter.
(default is NULL)
Show Sample XML response
Activate new DID

Add the specified DID to your account.

Request Type: activate_new_did

Parameter Type [?] Requirement Description
phone_number digits[10-15] Optionally Required Value must be a valid phone_number.
did_id integer Optionally Required Value must be a valid did_id.
Show Sample XML response
Order New DIDs

Request dids from a specific ratecenter or with a certain prefix that couldn't not be found in the inventory.

Request Type: order_new_dids

Parameter Type [?] Requirement Description
prefix digits Optionally Required Value must be a valid 6 digits NPA/NXX code for local or an international code with country code but without the 011.
(default is NULL)
ratecenter_id digits[6] Optionally Required Value must be a 6 digits ratecenter.
(default is NULL)
NOTE : A ratecenter may contain more than one NPA/NXX combination, you will receive one at random.
type string Optional Value must be one of the following : "local", "international".
(default is local)
quantity integer Required Value must be valid number.
prefix_preference string Optional Value must be one of the following: "in_ratecenter", "prefix_only".
(default is "in_ratecenter")
This parameter indicates if you require the specific NPA/NXX given or if you only need a number in the ratecenter.
NOTE : You cannot use prefix_only without setting `prefix` or if type is international.
sequential string Optional Value must be one of the following: "random", "sequential".
(default is "random")
t38_support string Optional Value must be one of the following: "optional", "required".
(default is "optional")
This parameter indicates if you require t38 support for your did.
capacity string Optional Value must be one of the following: "1-5", "5-25", "25+".
(default is "1-5")
This parameter indicates how many simultanious call this number will have at peak usage.
comments string Optional Value must be a 6 digits ratecenter.
(default is NULL)
Get list of DID area codes

This request type will provide information regarding available are codes. If you wish to get details about a specific area code, you may specify the `npa` parameter to do so.

Request Type: get_did_areacodes

Parameter Type [?] Requirement Description
npa digits[3] Optional Value must be a 3 digits NPA area code.
(default is NULL)
ratecenter_id digits[6] Optional Value must be a 6 digits ratecenter.
(default is NULL)
country_id integer Optional Value must be a valid `country_id`.
state_id integer Optional Value must be a valid `state_id`.
Show Sample XML response
Get list of DID exchanges

Get a list of available ratecenter exchanges by providing an area code or optionally a specific prefix. This is the request type to use if you wish to check the portability of availability of a ratecenter.

Note: It is recommended to store this information in your database and update once a day to avoid extra requests.

Request Type: get_did_exchanges

Parameter Type [?] Requirement Description
npa digits[3] Optionally Required Value must be a 3 digits NPA area code.
(default is NULL)
nxx digits[3] Optional Value must be a 3 digits NXX prefix.
(default is NULL)
ratecenter_id digits[6] Optionally Required Value must be a 6 digits ratecenter.
(default is NULL)
portability integer Optional Value must be 1 or 0.
(default is both)
availability integer Optional Value must be 1 or 0.
(default is both)
updated_since date Optional Will return all entries updated since given date. Must be a valid date.
(default is NULL)
result_limit integer Optional Value must be between 1 and 1000
(default is 25)
result_offset integer Optional Value must be a valid number
(default is NULL)
Show Sample XML response
Get list of Ratecenters

Get a list of available ratecenters by providing an area code or optionally a specific prefix. This is the request type to use if you wish to check the origin of a call and details about the ratecenter.

Note: When only providing NPA, it is recommended to use a reasonable result_limit to avoid extraneous load.

Request Type: get_ratecenters

Parameter Type [?] Requirement Description
npa digits[3] Optionally Required Value must be a 3 digits NPA area code.
(default is NULL)
nxx digits[3] Optional Value must be a 3 digits NXX prefix.
(default is NULL)
ratecenter_id digits[6] Optionally Required Value must be a 6 digits ratecenter.
(default is NULL)
updated_since date Optional Will return all entries updated since given date. Must be a valid date.
(default is NULL)
result_limit integer Optional Value must be between 1 and 1000
(default is 25)
result_offset integer Optional Value must be a valid number
(default is NULL)
Show Sample XML response
Get Peers details

If you wish to get details of a specific peer, you simply have to pass the `client_peer_id`. If no additional parameter is specified, the complete list of peers will be returned.

Request Type: get_peers

Parameter Type [?] Requirement Description
client_peer_id integer Optional Value must be a valid `client_peer_id`.
(default is NULL)
Show Sample XML response
Update Peer

You can update the configuration of a peer with this request type.

Note: Not all the option for peers are available through the API. Please request any new feature to our support department.

Request Type: update_peer

Parameter Type [?] Requirement Description
client_peer_id
integer Required Value must be a valid `client_peer_id`
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
host_type string Optional Value must be one of the following: "dynamic" or "static"
(default is NULL)
host string Optional Value must be a valid ip address
password string Optional Value must be alphanumeric string from 6 to 32 characters.
callerid_name string Optional Value must be alphanumeric string from 3 to 15 characters.
callerid_number digits [10] Optional Value must be a valid phone number of 10 digits.
callerid_mode string Optional Value must be one of the following: "global", "privacy", "custom" or "device"
codecs enum Optional Value must be one (or more, comma separated) of the following: "g729", "ulaw", "alaw", "g726", "gsm" or "ilbc"
dtmf_mode string Optional Value must be one of the following: "rfc2833", "inband", "info" or "auto"
force_ring_signal integer Optional 1 = enabled, 0 = disabled
(default is 0)
enable_nat integer Optional 1 = enabled, 0 = disabled
(default is 0)
enable_reinvite integer Optional 1 = enabled, 0 = disabled
(default is 0)
enable_recording integer Optional 1 = enabled, 0 = disabled
(default is 0)
ondemand_recording integer Optional 1 = enabled, 0 = disabled
(default is 0)
enable_dnis integer Optional 1 = enabled, 0 = disabled
(default is 0)
enable_notification integer Optional 1 = enabled, 0 = disabled
(default is 0)
client_mailbox_id integer Optional Value must be a valid `client_mailbox_id`
enable_auth integer Optional 1 = enabled, 0 = disabled
(default is 0)
auth_username string Optional Value must be alphanumeric string from 3 to 32 characters.
enable_qualify integer Optional 1 = enabled, 0 = disabled
(default is 0)
qualify integer Optional Value must be between 2 000 and 60 000 (inclusively)
default_ip string Optional Value must be a valid ip address
client_filter_ids Array Optional Value must be one or more valid client_filter_id.
(default is NULL)
status string Optional Value must be one of the following: "enabled" or "disabled"
comments string Optional  
Get voice mailboxes details

Get details for a single voice mailbox or the entire list by omitting the `client_mailbox_id`.

Request Type: get_mailboxes

Parameter Type [?] Requirement Description
client_mailbox_id integer Optional Value must be a valid `client_mailbox_id`.
(default is NULL)
Show Sample XML response
Update Mailbox

Allows you to create or simply update a mailbox.

Request Type: update_mailbox

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_mailbox_id
integer Optionally required If mode is "update", value must be a valid `client_mailbox_id`
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
passcode digits[4-12] Optional Value must be a number from 4 to 12 characters.
email string Optional Value must be a valid email address.
enable_mail_notification integer Optional 1 = enabled, 0 = disabled
(default is 0)
contact_name string See description Required if enable_mail_notification is set to 1. Must be between 4 to 60 characters.
enable_peer_notification integer Optional 1 = enabled, 0 = disabled
(default is 0)
notification_peers string See description Required if enable_peer_notification is set to 1. Must be between 1 and 10 peer ids (comma separated).
(default is 0)
notification_duration integer See description Required if enable_mail_notification and enable_peer_notification is set to 1. Must be between 5 and 60 minutes.
(default is 0)
status string Optional Value must be one of the following: "enabled" or "disabled"
comments string Optional  
Get extensions details

Get the full list of extensions or you can get a single entry by providing `client_extension_id`.

Request Type: get_extensions

Parameter Type [?] Requirement Description
client_extension_id integer Optional Value must be a valid `client_extension_id`.
(default is NULL)
Show Sample XML response
Update Extension

This request type allows you to create a new extension or update configuration of an existing extension.

Request Type: update_extension

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_extension_id
integer Optionally required If mode is "update", value must be a valid `client_extension_id`
extension integer Optional Value must be a number between 1 000 and 9 999 (inclusively).
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
client_peer_ids array Optional Values must valid `client_peer_id`.
peer_timeout string Optional Value must valid one of the following: "disabled", "2", "5", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55".
enable_peer integer Optional 1 = enabled, 0 = disabled
(default is 0)
forward_number integer Optional Value must be a valid phone number of 10 digits.
(default is NULL)
forward_timeout string Optional Value must valid one of the following: "disabled", "2", "5", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55".
enable_forwarding integer Optional 1 = enabled, 0 = disabled
(default is 0)
client_mailbox_id integer Optional Value must valid `client_mailbox_id`.
enable_voicemail integer Optional 1 = enabled, 0 = disabled
(default is 0)
status string Optional Value must be one of the following: "enabled" or "disabled"
comments string Optional  
Get account details

You can get some of the account details by using this request type. More information related to account is also provided in request types get_account_preferences and get_funding_details.

Request Type: get_account_details

Parameter Type [?] Requirement Description
- - - -
Show Sample XML response
Get account preferences

This request type will provide details for information found in clients sections Account Preferences and Global Settings.

Request Type: get_account_preferences

Parameter Type [?] Requirement Description
- - - -
Show Sample XML response
Get funding details

This request will allow you to get your account's funding details and status.

Note: The value returned for account_balance and funds_left are negative amount if not followed by 'CR'.

Request Type: get_funding_details

Parameter Type [?] Requirement Description
- - - -
Show Sample XML response
Get billing activity

This request will provide a list of invoices, payments, credits and returns and refunds. If date range is not provided, the complete list of transactions will be returned.

Request Type: get_billing_activity

Parameter Type [?] Requirement Description
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
date_to date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Show Sample XML response
Get countries

Get a list of countries, their country code and country ID for use with other request types.

Note: It is recommended to populate your database with this information once to avoid making extra requests.

Request Type: get_countries

Parameter Type [?] Requirement Description
- - - -
Show Sample XML response
Get states

Get a list of states/provinces, their state code and state ID for use with other request types.

Note: It is recommended to populate your database with this information once to avoid making extra requests.

Request Type: get_states

Parameter Type [?] Requirement Description
country_id integer Required Value must be a valid `country_id`.
Show Sample XML response
Get issues types

Retreive the list of possible issues, description and their issue ID for use with `report_call_issue` request type.

Note: It is recommended to store this information in your database and update once a month to avoid extra requests.

Request Type: get_issues_types

Parameter Type [?] Requirement Description
- - - -
Show Sample XML response
Get rates

Allows you to obtain a list of destinations along with their rate. You can optionally provide a dialing prefix identified as `code` or provide the `country_id` to get the matching results as long as you provide either one of them.

Request Type: get_rates

Parameter Type [?] Requirement Description
code string Optionally required Value must be a valid `code_prefix`.
country_id integer Optionally required Value must be a valid `country_id`.
state_id integer Optional Value must be a valid `state_id`.
Show Sample XML response
Get plans

Get the list of current plans available along with their included services.

Request Type: get_plans

Parameter Type [?] Requirement Description
- - - -
Show Sample XML response
Get E911 provisioned status

Returns provisioned status of a DID

Note : Will return all e911 endpoints locations if no argument is given. If both argument are given, the client_endpoint_id will be used.

Request Type: get_e911

Parameter Type [?] Requirement Description
phone_number
integer Optionally required Value must be a valid phone number of 10 digits. ( No space or - symbol )
client_endpoint_id integer Optionally required Value must be a valid `client_endpoint_id`
Show Sample XML response
Check address validity for E911

Verify if an address is valid with the E911 service.

IMPORTANT : This function may return failed and still contain alternate addresses until an exact match is provided.. See below for example

Request Type: check_e911

Parameter Type [?] Requirement Description
phone_number
integer Required Value must be a valid `phone_number` ( No space or - symbol )
civic_number integer Required Value must be a valid `civic_number`
street string Required Must be an exact match to the street name.
city string Required Must be an exact match to the city name.
state_code string Optionaly Required Value must be a valid 2 letter state code.
state_id integer Optionaly Required Value must be a valid `country_id`
country_code string Optionaly Required Value must be a valid 2 letter country code.
country_id integer Optionaly Required Value must be a valid `country_id`
postal_code string Required Must be a valid `postal_code`
address_type string Optional Must be one of the following : "apartment", "basement", "building", "department", "floor", "front", "hanger", "key", "lobby", "lot", "lower", "office", "penthouse", "pier", "rear", "room", "side", "slip", "space", "stop", "suite", "trailer", "unit", "upper"
address_type_number string Optional Must be a valid `address_type_number`
Show View alternate addresses error sample XML response
Associate peer to did for E911

Associate a peer to a provisioned DID.

IMPORTANT : Ignore if the trunk associated is a server and many different endpoint addresses are provisioned.

Request Type: associate_e911

Parameter Type [?] Requirement Description
client_did_id
integer Optionally required Value must be a valid `client_did_id`
phone_number
integer Optionally required Value must be a valid phone number of 10 digits. ( No space or - symbol )
client_endpoint_id integer Optionally required Value must be a valid `client_endpoint_id`
client_peer_id integer Required Value must be a valid `client_peer_id`
Disassociate peer to did for E911

Disassociate a peer to a provisionned DID.

Request Type: disassociate_e911

Parameter Type [?] Requirement Description
client_peer_id integer Required Value must be a valid `client_peer_id`
Update E911 provisioned address.

Update the provisioned address for a did for the e911 service.

IMPORTANT : This function may return failed and still contain alternate addresses until an exact match is provided. See below for example

Request Type: update_e911

Parameter Type [?] Requirement Description
phone_number
integer Required Value must be a valid phone number of 10 digits. ( No space or - symbol )
first_name string Required Value must be a valid `first_name`
last_name string Required Value must be a valid `last_name`
civic_number integer Required Value must be a valid `civic_number`
street string Required Must be an exact match to the street name.
city string Required Must be an exact match to the city name.
state_code string Optionally Required Value must be a valid 2 letter state code.
state_id integer Optionally Required Value must be a valid `country_id`
country_code string Optionally Required Value must be a valid 2 letter country code.
country_id integer Optionally Required Value must be a valid `country_id`
postal_code string Required Must be a valid `postal_code`
language string Optional Value must valid one of the following: "en", "fr". Default is account preferred language. Ignored outside of Canada.
address_type string Optional Must be one of the following : "apartment", "basement", "building", "department", "floor", "front", "hanger", "key", "lobby", "lot", "lower", "office", "penthouse", "pier", "rear", "room", "side", "slip", "space", "stop", "suite", "trailer", "unit", "upper"
address_type_number string Optional Must be a valid `address_type_number`
Show View alternate addresses error sample XML response
Delete E911 provided address

Delete the provisioned address of a did. Also remove any association for peers using this address.

Note : Only one of the arguments is needed. If both are given, the client_endpoint_id will override.

Request Type: delete_e911

Parameter Type [?] Requirement Description
phone_number
integer Optionally required Value must be a valid phone number of 10 digits. ( No space or - symbol )
client_endpoint_id integer Optionally required Value must be a valid `client_endpoint_id`
Get Network Status

If you wish to get the list of network status. If no additional parameter is specified, the first 5 entries will be returned.

Request Type: get_network_status

Parameter Type [?] Requirement Description
limit integer Optional Value must be a valid positive number.
(default is 5)
offset integer Optional Value must be a valid positive number.
(default is 0)
Show Sample XML response
Dispatch Call

This request allows you to establish a call between two distinct endpoints. It can be used to connect an agent to a local phone number or link any other combinations of the two endpoint types.

The meta_data parameter can be used to store any information about the call being dispatched in order to be retrieved later with get_calls request. This will work great with serialized data.

Note: Recordings of 2 seconds or less are automatically deleted.
Note: Both endpoints will be imported in the call history of account that made the request regardless if peer belongs to another account.

Request Type: dispatch_call

Parameter Type [?] Requirement Description
source_type string Required Value must be either "number" or "peer".
source digits [10] alphanum [6-16] Required If type is "number" then value must be valid phone number of at least 10 digits.
If type is "peer" then value must be a valid peer username.
destination_type string Required Value must be either "number" or "peer".
destination digits [10] alphanum [6-16] Required If type is "number" then value must be valid phone number of at least 10 digits.
If type is "peer" then value must be a valid peer username.
callerid_name string [3-15] Optional Value must be alphanumeric string from 3 to 15 characters.
(default is account's global `callerid_name`)
callerid_number string [10] Optional Value cannot start with the following: "1", "800", "888", "877", "866" or "855"
(default is account's global `callerid_number`)
enable_recording integer Optional

1 = enabled, 0 = disabled
(default is 0)

wait_time integer
Optional Value must be between 5 and 60 (inclusively)
(default is 15)
meta_data string Optional Any value is accepted.
Error types

The following information gives you details about possible errors returned by the different request types.

Error type Description
auth_username_invalid Auth username is invalid.
auth_username_required Auth username is required.
authentication_failed Authentication failed. Please verify 'client_account_id' and 'auth_token'.
authentication_token_required Auth token is required.
callerid_name_invalid Caller ID name is invalid.
callerid_name_required Caller ID name is required.
callerid_number_invalid Caller ID number is invalid.
callerid_number_required Caller ID number is required.
callerid_rejection_notice Some providers might reject toll free Caller ID.
client_account_id_invalid Client account ID is invalid.
client_account_id_required Client account ID is required.
client_did_id_invalid Client DID ID is invalid.
client_extension_id_invalid Client account ID is invalid.
client_mailbox_id_invalid Client mailbox ID is invalid.
client_peer_id_invalid Client peer ID is invalid.
country_id_invalid Country ID is invalid.
country_id_required Country ID is required.
date_from_invalid Date from is invalid.
date_to_invalid Date to is invalid.
email_invalid Email address is invalid.
email_required Email address is required.
forward_number_invalid Forward number is invalid.
forward_number_required Forward number is required.
forward_timeout_invalid Call forward ring timeout is invalid.
forward_timeout_required Call forward ring timeout is required.
friendly_name_invalid Friendly name is invalid.
friendly_name_required Friendly name is required.
internal_error-database_error There was an internal error with our database.
internal_error-invalid_argument Invalid argument.
language_invalid Language is invalid.
mailbox_invalid Mailbox is invalid.
mode_invalid Mode is invalid.
npa_invalid NPA is invalid.
nxx_invalid NXX is invalid.
npa_required NPA is required.
nxx_required NXX is required.
options_invalid Options are invalid.
password_invalid Password is invalid.
password_mismatch The password verification did not match.
password_required Password is required.
peer_required Peer is required.
peer_timeout_invalid Peer ring timeout is invalid.
peer_timeout_required Peer ring timeout is required.
peers_to_ring_limit_reached Please choose a maximum of 5 peers.
phone_number_invalid Phone number is invalid.
request_type_invalid Request type is invalid.
request_type_not_implemented Request type is not implemented.
request_type_required Request type is required.
required_parameter_not_found Required parameters missing.
result_limit_invalid Result limit is invalid.
result_offset_invalid Result offset is invalid.
state_id_invalid State ID is invalid.
status_invalid Status is invalid.
status_required Status is required.
username_invalid Username is invalid.
username_required Username is required.
Error type Description
destination_invalid Destination is invalid.
destination_required Destination is required.
destination_type_invalid Destination type is invalid.
destination_type_required Destination type is required.
enable_recording_invalid Enable recording value is invalid.
global_callerid_name_undefined Global caller ID name is not defined.
max_retries_invalid Maximum retries is invalid.
retry_delay_invalid Retry delay is invalid.
socket_error A socket error occured.
source_invalid Source is invalid.
source_required Source is required.
source_type_invalid Source type is invalid.
source_type_required Source type is required.
wait_time_invalid Wait time is invalid.
Error type Description
direction_invalid Direction is invalid.
unique_id_invalid Unique ID is invalid.
Error type Description
code_invalid Code is invalid.
search_parameters_required Search parameters are required.
Error type Description
unique_id_invalid Unique ID is invalid.
call_issue_id_invalid Call Issue ID is invalid.
Error type Description
call_hash_invalid Call hash is invalid.
call_recording_id_invalid Call recording id is invalid.
recording_hash_invalid Recording hash is invalid.
Error type Description
amount_invalid Amount is invalid.
amount_required Amount is required.
bank_account_number_invalid Bank account number is invalid.
bank_account_number_required Bank account number is required.
bank_account_type_invalid Bank account type is invalid.
bank_account_type_required Bank account type is required.
bank_name_invalid Bank name is invalid.
bank_name_required Bank name is required.
bank_routing_number_invalid Bank routing number is invalid.
bank_routing_number_required Bank routing number is required.
billing_contact_not_found Account's billing contact could not be found.
credit_card_cvd_invalid The credit card CVD number is invalid.
credit_card_cvd_required The credit card CVD number is required.
credit_card_expiration_month_invalid The credit card expiration month is invalid.
credit_card_expiration_month_required The credit card expiration month is required.
credit_card_type_invalid The credit card type is invalid.
credit_card_type_required The credit card type is required.
credit_card_expiration_year_invalid The credit card expiration year is invalid.
credit_card_expiration_year_required The credit card expiration year is required.
credit_card_number_invalid The credit card number is invalid.
credit_card_number_required The credit card number is required.
currency_invalid Currency is invalid.
currency_not_supported Currency is not supported for given type of payment.
currency_required Currency is required.
minimum_amount_required The minimum amount is not met.
payment_attempt_failed Payment attempt has failed.
payment_denied Payment denied.
payment_method_invalid Payment method is invalid.
payment_method_required Payment method is required.
Error type Description
forward_number_used_by_did Forward number already in use.
Error type Description
extension_already_in_use Extension is already in use.
extension_invalid Extension is invalid.
extension_required Extension is required.
Error type Description
default_mailbox_dependency You cannot disable this mailbox because it is set as default.
mailbox_did_dependency You cannot disable this mailbox because it is associated to a DID number.
passcode_invalid Passcode is invalid.
passcode_required Passcode is required.
voice_mailboxes_limit_reached Voice mailboxes limit is reached.
Error type Description
callerid_mode_invalid Caller ID mode is invalid.
callerid_mode_required Caller ID mode is required.
codecs_invalid Codecs are invalid.
codecs_required Codecs are required.
default_ip_invalid Default IP is invalid.
dtmf_invalid The dtmf mode is invalid.
global_callerid_infos_undefined Global caller ID settings are not defined.
host_type_invalid Host type is invalid.
host_type_required Host type is required.
peer_did_dependency You cannot disable this peer because it is associated to a DID number.
peer_excluded_from_sync This peer is currently excluded from synchronization and changes will not affect live configuration.
peer_exist The username is already in use.
peers_limit_reached Peers limit is reached.
qualify_invalid Qualify milliseconds are invalid.
qualify_required Qualify milliseconds are required.
type_invalid The peer protocol is invalid.
Error type Description
alternate_address_provided Alternate Address is Provided.
client_endpoint_id_not_found Client Endpoint ID Not Found.
client_peer_id_not_found Client Peer ID Not Found.
client_did_id_not_found Client DID ID Not Found.
phone_number_not_found Phone Number Not Foudn.
no_e911_endpoint_found Number is not provisioned.
no_e911_endpoint_found Number is not provisioned.
civic_number_not_found Civic number not found.
street_not_found Street not found.
city_not_found City not found.
state_not_found State not found.
country_not_found Country not found.
first_name_not_found First name not found.
last_name_not_found Last name not found.
postal_code_not_found Postal Code not found.
last_endpoint_was_deleted The last endpoint was deleted. Any calls to 911 after this notice and before another DID is provisionned will be billed an E911 unprovision fee in your account.
entry_is_default_endpoint The endpoint is currently the default endpoint for the account. Set the default to another one before deleting this one.
Error type Description
prefix_required No prefix nor ratecenter id was given.
prefix_invalid Prefix is not valid.
ratecenter_id_invalid Ratecenter id is not valid.
type_invalid Type must be either "local" or "international".
quantity_required Quantity is required.
quantity_invalid Quantity must be a number above 0 and under 1000.
prefix_preference_invalid Preference must be either "in_ratecenter" or "prefix_only".
sequential_invalid Preference must be either "random" or "sequential".
t38_support_invalid Preference must be either "optional" or "required".
capacity_invalid Preference must be either "1-5", "5-25" or "25+".
prefix_not_found Could not find the prefix in our database.
ratecenter_id_not_found Could not find the ratecenter id in our database.
could_not_send An error occurred while trying to send the request, please contact us.
Api Metadata
Metadata update (input)
Metadata can be submitted as serialized_metadata or raw_metadata.

Parameter Type [?] Requirement Description
serialized_metadata serialized array Optional Value must be a valid array converted to a serialized string (using php's serialize).
(default is NULL)
raw_metadata string Optional Value can be anything and will be returned as such.
(default is NULL)
Applicable request types : update_did, update_peer, update_mailbox, update_extension.
Retreive metadata (output)

Metadata is output in the main <metadata> tag.
Any data in the metadata field of the entry will be returned as CDATA under the <raw_metadata> tag.
If the data was supplied as an array, or pair of attributes (also called Name-Value Pairs), it will be returned as an XML tree under the <metadata_attributes> tag with an attribute_count property.

Sample XML response
<?xml version="1.0" encoding="utf-8"?>
    <response>
 
        ...
 
            <metadata>
                <raw_metadata>
                    <![CDATA[a:3:{s:13:"tout_le_monde";s:8:"en parle";s:6:"piment";s:4:"fort";s:5:"super";s:3:"man";} ]]>
                </raw_metadata>
                <metadata_attributes attribute_count="3">
                    <tout_le_monde><![CDATA[en parle ]]></tout_le_monde>
                    <piment><![CDATA[fort ]]></piment>
                    <super><![CDATA[man ]]></super>
                </metadata_attributes>
            </metadata>
    </response>
Applicable request types : get_dids, get_peers, get_mailboxes, get_extensions.
Examples
Synchronizing call history periodically

Available soon.

Dispatch a call from one place to another

Available soon.

Setting call forward on a DID number
Available soon.
Security Notes

Available soon.

Troubleshooting

Available soon.