VoiceMeUp Developer's Resource
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 (Obsolete in v1.1) Value must be a valid `client_account_id` of 8 digits.
username string Optionally Required (v1.1) Value must be a valid `username`.
client_user_id digits[4-8] Optionally Required (v1.1) Value must be a valid `client_user_id` of 4 to 8 digits.
auth_token hex[32] Required Value must be a valid `auth_token` of 32 hexadecimal characters (lowercase).
request_type string Required (Obsolete in v1.1) Value must be a valid `request_type`.
List of available request types is available here.
output_format string Optional (Obsolete in v1.1) Value must be a valid `output_format`.
List of available output formats is available here.
(default XML)
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.

v1.0 (Deprecated)
https://developer.voicemeup.com/xml_engine/xml_engine.php?request_type=get_request_types&client_account_id=80012345&auth_token=1A2B3C4D5E6 ...
v1.1
https://clients.voicemeup.com/api/v1.1/json/get_request_types?client_user_id=123456&auth_token=1A2B3C4D5E6 ...
https://client.beevox.com/api/v1.1/json/get_request_types?client_user_id=123456&auth_token=1A2B3C4D5E6 ...
Will also work with your whitelabel custom domain
Response format

Responses are only formatted in two formats:

Show Sample XML response
Show Sample JSON response
Webhook

A webhook is used to notify an external system of an event. The URL given will be called when the configured event is triggered. Each webhook's return is unique, please consult the method documentation for more info.

Some VoiceMeUp services have been configured to support this feature. Here are the methods that support it :

Limitation

To avoid abuse, the XML Engine API has a hourly limit. Some request types have a specific limit as shown below, any request not listed below falls in the shared pool. Once the limit is reached, we will send you an email about the abuse. If the limit is exceeded too greatly, we will refuse subsequent API requests for the next 60 minutes with the error code "requests_hard_limit_exceeded".

Request Type Limit per hour
delete_faxes 1500
delete_recordings 1500
delete_voicemails 1500
dispatch_call 900
voicemail_broadcast 900
queue_fax 600
queue_sms 600
shared_pool (all other request types combined) 1200
Routing types

internal, emergency_call, directory_assistance, international_termination, international_origination, local_termination, local_origination, tollfree_origination, tollfree_termination, paypercall_origination, total

Message types

sms_inbound, sms_outbound, mms_inbound, mms_outbound, total

Storage types

recordings_size, voicemails_size, medias_size, faxes_size, mms_size, export_size, pbx3cxmedia_size, pbx3cxbackup_size, total

Request Types
Get request types

Get all available request types

Request Type: get_request_types

Show Sample XML response
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 `call_hash`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".
latest_hours int Optionally Required Must be an int above 0.
call_hash string Optionally Required Value must be a 32 characters alphanumeric call_hash referencing the last call previously returned by your last request made with `get_calls`.
unique_id string Deprecated Deprecated, use `call_hash` instead.
direction string Optional Value must be one of the following: "inbound" or "outbound"
(default is NULL)
routing_type string Optional Value must be one of the following: "undefined","internal","emergency_call","directory_assistance","international_termination","international_origination","local_termination","local_origination","tollfree_origination","tollfree_termination"
More than one value can be used separated by comma
(default is NULL)
disposition string Optional Value must be one of the following: "answered","busy","failed","no_answer","cancelled","denied","invalid","unknown"
More than one value can be used separated by comma
(default is NULL)
result_limit integer Optional Value must be between 1 and 1000
(default is 25 with date_to and date_from set, 1 with call_hash set)
result_offset integer Optional Value must be a valid number
(default is NULL)
extras string Optional Value must be one of the following: "yes", "no". Will return the following extra fields :
failure_code, sip_response_code, account_usage_inbound
account_usage_outbound, account_call_limit, subaccount_usage_inbound
subaccount_usage_outbound, subaccount_call_limit, subaccount_channel_inbound, subaccount_channel_outbound",channel_usage_inbound
channel_usage_outbound, channel_usage_excess
(default is no)
metadata string Optional Value must be one of the following: "yes", "only", "all" or "no"
(default is no)
routing_details string Optional Value must be one of the following: "yes" or "no"
(default is no). This will return more details about the source and destination.
client_channel_id integer Optional Value must be a valid `client_channel_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
Show Sample XML response
Get call statistics
Gather statistical information about calls for given period.
Request Type: get_calls_stats

Parameter Type [?] Requirement Description
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Max date range between `date_to` and `date_from` is 12 months.
(default is today)
date_to date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Max date range between `date_to` and `date_from` is 12 months.
(default is today)
client_subaccount_ids enum Optional List of all the `client_subaccount_id` wanted separated by a comma.
Max 10 `client_subaccount_id`.
(default is main_account and whole_account (main_account + subaccounts))
routing_types enum Optional List of all the client routing types wanted separated by a comma.
(default is NULL)
Show Sample XML response with no subaccount_ids specified.
Show Sample XML response with subaccount_ids specified.
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)
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
date_to date Optional If set, date_from must also be set.
Value must be a valid date formatted as "YYYY-MM-DD".
latest_hours int Optional Must be an int above 0.
status enum Optional Value must be one (or more, comma separated) of the following: "unverified", "verified" or "deleted"
(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 call_hash setted)
result_offset integer Optional Value must be a valid number
(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)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_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 a virtual fax profile, 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)
client_fax_profile_id integer Optional Value must be a valid `client_fax_profile_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
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".
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)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
Show Sample XML response
Update Fax Profile

Allows you to create or simply update a fax profile.

Request Type: update_fax_profile

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_fax_profile_id
integer Optionally required If mode is "update", value must be a valid `client_fax_profile_id`
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
local_ident string Required Value must be alphanumeric string from 2 to 20 characters.
fax_header string Required Value must be alphanumeric string from 2 to 20 characters.
callerid_name string Required Value must be alphanumeric string from 3 to 15 characters.
callerid_number digits [10] Required Value must be a valid phone number of 10 digits.
contact_name string Optional Value must be alphanumeric string from 4 to 60 characters.
email string Required Value must be a valid email address.
language string Required Value must be one of the following : "en" or "fr".
allowed_senders string Required List of all the `allowed_senders` wanted separated by a comma.
retry_limit integer Optional The number of times we should retry sending.
(default is 2)
page_format string Required Value must be one of the following : "letter", "legal", "a4"
resolution string Required Value must be one of the following : "standard", "fine"," super_fine", "ultra_fine", "color"
callback_url string Optionally required Must be a valid Webhook. Can contain GET arguments. Details will be sent as JSON in the POST body.
Required if option "enable_callback" is selected.
backup_url string Optional Must be a valid Webhook. Can contain GET arguments. Details will be sent as JSON in the POST body.
Will be called if `callback_url` does not respond.
options Array Optional Value must be one or more of the following : "inbound_completed_notification", "inbound_failed_notification", "outbound_completed_notification", "outbound_failed_notification", "enable_cover_page", "enable_inbound_send_attachment", "enable_outbound_send_attachment", "enable_callback".
(default is NULL)
status string Required Value must be one of the following: "enabled" or "disabled"
comments string Optional  
Delete fax profile

Delete a fax profile from your account.

Request Type: delete_fax_profile

Parameter Type [?] Requirement Description
client_fax_profile_id integer Required Value must be a valid `client_fax_profile_id`.
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)
page_format string Optional Value must be one of the following : 'letter', 'legal', 'a4'.
(Default is fax profile page_format)
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)
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 integer Optional Value must be a valid `ratecenter_id`.
(default is NULL)
district string Optional Value must be a valid `district`.
(default is NULL)
state_id integer Optional Value must be a valid `state_id`.
(default is NULL)
country_id integer Optional Value must be a valid `country_id`.
(default is NULL)
options enum Optional Only entries matching all the given options will be returned.
Value must be one (or more, comma separated) of the following:
'enable_ivr','enable_disa','enable_director','enable_fax','enable_peer',
'enable_forwarding','enable_uri','enable_voicemail','enable_recording','ondemand_recording',
'announce_monitor','announce_caller','enable_filtering','enable_conference','enable_disa',
'enable_uri','force_ring_signal','discard_redirect','confirm_required','enable_sms',
'enable_sms_email_notify','enable_sms_forwarding','enable_sms_callback','enable_sms_callback_retry',
'enable_queue' (default is NULL)
client_peer_id integer Optional Value must be a valid `client_peer_id`.
Since `peer_to_rings` may contain multiple `client_peer_id`, if the given value matches one,
the entry will be returned
(default is NULL)
client_mailbox_id integer Optional Value must be a valid `client_mailbox_id`.
announce_media_file_id integer Optional Value must be a valid client_media_file_id.
bridge_uri string Optional Must be a valid string uri of 240 or less characters.
pickup_group_ids string Optional Must be a valid string og pickup group ids of 64 or less characters.
client_conference_profile_id integer Optional Must be a valid `client_conference_profile_id`.
client_fax_profile_id integer Optional Value must be a valid `client_fax_profile_id`.
dnis_rewrite string Optional Must be 30 or less characters.
confirm_media_file_id integer Optional Value must be a valid client_media_file_id.
playback_media_file_id integer Optional Value must be a valid playback_media_file_id.
sms_autoreply_message string Optional Must be a valid string of 160 or less characters.
recording_notify_recipient_name string Optional Must be a valid string of 255 or less characters.
peer_failover_causes string Optional Must be a valid string of 240 or less characters.
recording_notify_recipient_email string Optional Must be a valid string of 255 or less characters.
type
string Optional Value must be one of the following: 'local', 'tollfree', 'paypercall', 'international', 'inum', 'shadow', 'interexchange'
usage_type
string Required Value must be one of the following: 'default', 'paging', 'parking', 'conference', 'disa', 'uri'
sms_dnis_rewrite string Optional Must be 30 or less characters.
sip_response digits [3] Optional Value must be a 3 digits sip response
(default is NULL)
exclude_e411_list integer Optional Value must be 0 or 1
exclude_e911_list integer Optional Value must be 0 or 1
t38_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if your did(s) support t38/fax.
sms_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if your did(s) support SMS.
mms_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if your did(s) support MMS.
enable_voicemail bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if your did(s) enable voicemail.
ondemand_recording bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if your did(s) enable ondemand recording.
enable_fax bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if your did(s) enable fax.
client_channel_id integer Optional Value must be a valid `client_channel_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
status enum Optional Value must be one of the following: "enabled", "deleted", "disabled"
(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
preserve_missing_data
boolean Optional This will allow you to modify only the provided fields when updating an entry (default is FALSE)
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.
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)
send_dtmf string Optional Must be valid DTMF tones (0-9,a,b,c,d,w and W).
voice_language string Optional Value must valid one of the following: "en", "fr". Default is account preferred language.
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)
client_sms_profile_id integer Optional Value must be a valid `client_sms_profile_id`.
(default is NULL)
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)
peer_contact_mode string Optional Value must be one of the following : "sequential", "simultaneous" or "round_robin".
(default is NULL)
client_queue_ids enum Optional Value(s) must be valid client_queue_id(s) (comma separated).
(default is NULL)
bridge_uri string Optional Must be a valid SIP uri.
(default is null)
client_conference_profile_id string Optional Must be a valid `client_conference_profile_id`.
(default is null)
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)
announce_media_file_id string Optionally required Value must be a valid client_media_file_id.
(default is 0)

Required if `announce_caller` is set, will play the message to the callee before connecting the call.
monitor_media_file_id string Optional Value must be a valid client_media_file_id.
(default is 0)

If specified alongside the `announce_monitor` option, will override the default "This call may be recorded [...]" prompt played to the caller before connecting the call.
confirm_media_file_id string Optional Value must be a valid client_media_file_id.
(default is 0)

If specified alongside the `confirm_required` option, will play this message when asking the callee to confirm answering.
callerid_name_rewrite alphanum Optional Must be between 3 and 15 characters.
(default is null)
callerid_number_rewrite digits Optional Must be between 1 and 20 characters. Also supports the symbol '+'.
(default is null)
sms_notify_email string Optionally required Must be a valid email address.
(default is null)

Required if `enable_sms_email_notify` is set, will send an email if an sms was received.
sms_forward_number digits [15] Optionally required Value must be a valid phone number.
(default is null)

Required if `enable_sms_forwarding` is set, will forward sms to selected number.
sms_callback_url string Optionally required Must be a valid Webhook. Can contain GET arguments. Details will be sent as JSON in the POST body.
(default is null)

Required if `enable_sms_callback` is set.
sms_autoreply_message string Optionally required Must be a valid string of 160 or less characters.
(default is null)

Required if `enable_sms_autoreply` is set, will automatically reply with this text on every incoming SMS.
client_channel_id integer Optional Value must be a valid `client_channel_id`.
(default is 0)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
notify_callback_triggers Array Optionally required Value must be one (or more, comma separated) of the following: "on_create", "on_ring", "on_answer", "on_hangup", "on_test", "on_record" (default is NULL)

Required if `enable_notify_callback` is set, will set the triggers selected to the notify callback.
notify_callback_url string Optionally required Value must be a valid URL. If this value is changed, we will hit the url and expect an HTTP Code 200. The test hit will have the trigger on_test.
(default is NULL)

Required if `enable_notify_callback` is set, will set the callback URL to the one selected.
simultaneous_calls_limit integer Optional Value must be a number between 0 and 255
type
string Optional Value must be one of the following: 'local', 'tollfree', 'paypercall', 'international', 'inum', 'shadow', 'interexchange'
usage_type
string Required Value must be one of the following: 'default', 'paging', 'parking', 'conference', 'disa', 'uri'
recording_notify_recipient_name string Optional Must be a valid string of 255 or less characters.
recording_notify_recipient_email string Optional Must be a valid string of 255 or less characters.
peer_failover_causes string Optional Must be a valid string of 240 or less characters.
pickup_group_ids string Optional Must be a valid string of 64 or less characters.
sms_dnis_rewrite string Optional Must be 30 or less characters.
exclude_e411_list integer Optional Value must be 0 or 1
exclude_e911_list integer Optional Value must be 0 or 1
options Array Optional Value must be one or more of the following : "enable_forwarding", "enable_voicemail", "enable_peer", "ondemand_recording", "announce_monitor", "enable_recording", "enable_ivr", "enable_fax", "announce_caller", "enable_sms", "enable_sms_email_notify", "enable_sms_forwarding", "enable_sms_callback", "enable_sms_callback_retry", "enable_sms_autoreply", "enable_uri", "enable_georedundancy", "force_ring_signal", "discard_redirect", "confirm_required", "enable_filtering", "enable_director", "enable_notify_callback".
(default is NULL)
comments string Optional  
status enum Optional Value must be one of the following: "enabled" or "disabled"
Delete DID

Delete a did from your account.

Request Type: delete_did

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 )
Show Sample XML response
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_id`.
(default is NULL)
district string Optional Value must be a partial or complete district name. Complete match will be returned first.
(default is NULL)
state_id string Optional Value must be a `state_id`.
(default is NULL)
included_patterns string Optional Value must be a one or many of the following :
'all_numbers' will return all entries
'no_patterns' will return numbers with no pattern
'rare_number','pattern_double_digits','pattern_double_digits_pair','pattern_double_digits_trio','pattern_tripple_digits','pattern_quadruple_digits' will return numbers will match at least one of the given pattern
(default is all_numbers)
order string Optional Values must be one of the following : default, random.
(default is default)
t38_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if you require t38/fax support for your did(s).
sms_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if you require SMS support for your did(s).
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.
skip_notification bool Optional Will skip the new did assigned email.
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_id`.
(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 bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if you require t38/fax support for your did(s).
sms_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if you require SMS support for your did(s).
mms_support bool Optional Value must be one of the following: "1" or "0"
This parameter indicates if you require MMS support for your did(s).
capacity string Optional Value must be one of the following: "0", "1-2", "2-5", "5-10", "10-15", "15-25", "25-50", "50+".
(default is "1-2")
This parameter indicates how many simultaneous call this number will have at peak usage.
comments string Optional A comment to be displayed on your order.
Get port requests

If you wish to get details of a port request, you simply have to pass the `port_request_id` or PON. If no additional parameter is specified, the complete list of port requests will be returned.

Request Type: get_port_requests
Request Type Added on May 13th 2019

Parameter Type [?] Requirement Description
port_request_id int Optional Value can either be a valid `port_request_id` or a fully qualified PON 'PON00000000'.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
current_owner string Optional Will add a wildcard before and after the string comparison. Case and accent insensitive.
(default is NULL)
phone_number int Optional Will check for the number being ported. Does not search in numbers to keep or disconnect.
(default is NULL)
status enum Optional Value must be one (or more, comma separated) of the following: "not_ready", "sent_to_staff", "approved_by_staff", "rejected_by_staff", "rejected_by_client", "expired", "sent_to_provider", "cancelled_by_client", "tentative_confirm", "firm_confirm", "rejected_by_provider", "completed", "modified_by_staff"
(default is NULL)
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Will search for the firm date. Does not search in the tentative or requested date.
(default is NULL)
date_to date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Will search for the firm date. Does not search in the tentative or requested date.
(default is NULL)
Show Sample XML response
Update Port Request

You can update the port request with this request type.

Request Type: update_port_request

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
port_request_id integer Optionally required If mode is "update", value must be a valid `port_request_id`
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Optional Value must be alphanumeric string from 2 to 60 characters.
(default is NULL).
phone_number_type string Optionally Required Value must be one of the following: "local" or "tollfree"
phone_numbers string Optionally Required Value must be a valid phone number of 10 digits.
More than one value can be used separated by comma
phone_numbers_to_keep string Optional Value must be a valid phone number of 10 digits.
More than one value can be used separated by comma
(default is NULL).
phone_numbers_to_cancel string Optional Value must be a valid phone number of 10 digits.
More than one value can be used separated by comma
(default is NULL).
features string Optional Value must be one or more of the following : "sms", "mms", "t38"
(default is NULL).
capacity string Optionally Required Value must be one or more of the following : "1-2", "2-5", "5-10", "10-15", "15-25", "25-50", "50+"
requested_firm_date string Optional Value must be a valid date formatted as "YYYY-MM-DD".
Desired port date. Must be between 3 to 15 business days
(default is "As soon as possible").
organization string Optionally Required Value must be alphanumeric string from 2 to 60 characters.
organization_type string Optionally Required Value must be one of the following: "personal", "business"
current_provider string Optionally Required Value must be alphanumeric string from 2 to 60 characters.
current_reseller string Optional Value must be alphanumeric string from 2 to 60 characters.
(default is NULL).
current_reseller_account string Optional Value must be alphanumeric string from 2 to 60 characters.
(default is NULL).
box_number string Optional
civic_number integer Optionally Required Value must be a number.
street string Optionally Required Value must be alphanumeric string.
unit_number integer Optional Value must be a number.
city string Optionally Required Value must be alphanumeric string.
country_id integer Optionally Required Value must be a valid `country_id`
state_id string Optionally required If country_id is "38" or "223", must be a valid `state_id`.
state_other string Optionally required If country_id is not is "38" or "223", must be alphanumeric string.
postal_code string Optionally Required Must be a valid `postal_code`.
client_instructions string Optional Instructions to be provided to the carrier. Eg: "New BTN is 514-xxx-xxxx"
(default is NULL).
is_notify_creation bool Optional Value must be one of the following: "1" or "0"
(default is 0).
Create a kayako ticket immediately upon sending to staff
notification_client_user_id string Optionally Required Must be a valid `client_user_id`.
This user will receive the Kayako ticket notifications
extra_recipients string Optional Extra recipient to receive the Kayako notifications.
More than one value can be used separated by comma
(default is NULL).
loa file Optional Must be a valid file.
(default is NULL).
bill file Optional Must be a valid file.
(default is NULL).
other file Optional Must be a valid file.
(default is NULL).
send_to_staff bool Optionally Required Value must be one of the following: "1" or "0"
(default is 0).
Set to 1 to submit the port. Fields become required when trying to send to staff.
comments string Optional  
[raw_metadata] see doc see doc
Lookup DID

Lookup DID information.

Notice: Charges apply for this request type. Please contact your account manager for more details.
Request Type: lookup_did

Parameter Type [?] Requirement Description
phone_number digits[10-15] Required Value must be a valid phone_number.
Show Sample XML response
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] Optional 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] Optional Value must be a 6 digits `ratecenter_id`.
(default is NULL)
state_id integer Optional Value must be a valid `state_id`.
(default is NULL)
country_id integer Optional Value must be a valid `country_id`.
(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] Optional 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] Optional Value must be a 6 digits `ratecenter_id`.
(default is NULL)
state_id integer Optional Value must be a valid `state_id`.
(default is NULL)
country_id integer Optional Value must be a valid `country_id`.
(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 sms

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

Request Type: get_sms
Request Type Added on January 19th 2016

Parameter Type [?] Requirement Description
sms_log_id integer Optional Value must be a valid `sms_log_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
sms_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_sms`.
(default is NULL)
direction enum Optional Value must be one of the following: "inbound", "outbound"
(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)
source_number integer Optional Value must be valid phone number
(default is NULL)
destination_number integer Optional Value must be valid phone 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".
result_limit integer Optional Value must be between 1 and 1000
(default is 25 with date_to and date_from setd, 1 with sms_hash set)
Show Sample XML response
Delete SMS

Delete a SMS from your account.

Request Type: delete_sms

Parameter Type [?] Requirement Description
sms_log_id integer Required Value must be a valid `sms_log_id`.
Get SMS statistics
Gather statistical information about SMS and MMS for given period.
Request Type: get_sms_stats

Parameter Type [?] Requirement Description
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Max date range between `date_to` and `date_from` is 12 months.
(default is today)
date_to date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Max date range between `date_to` and `date_from` is 12 months.
(default is today)
client_subaccount_ids enum Optional List of all the `client_subaccount_id` wanted separated by a comma.
Max 10 `client_subaccount_id`.
(default is main_account and whole_account (main_account + subaccounts))
message_types enum Optional List of all the client message types wanted separated by a comma.
(default is NULL)
Show Sample XML response with no subaccount_ids specified.
Show Sample XML response with subaccount_ids specified.
Queue SMS

You can send a SMS with this request type. It is important to note that a DID with SMS support is required to use this feature.

Request Type: queue_sms

Request Type Added on November 9th 2015

Parameter Type [?] Requirement Description
client_did_id integer Optionally Required Value must be a valid `client_did_id`.
source_number digits [10] Optionally Required Value must be a valid phone number.
destination_number digits [10] Required Value must be a valid phone number.
message string [160] Optionally Required Value must be valid string up to 1000 characters. You must provide either a message or an attachment. Depending on carrier message may be split into multiple 160 character sms.
attachments file Optionally Required Value must be a valid file, only one file supported for now. You must provide either a message or an attachment.
retry_limit integer Optional Value must between 0 and 5.
(default is 0)
Show Sample XML response
Get SMS profiles

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

Request Type: get_sms_profiles
Request Type Added on June 6th 2019

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

Allows you to create or simply update a SMS profile.

Request Type: update_sms_profile
Request Type Added on June 6th 2019

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_sms_profile_id
integer Optionally required If mode is "update", value must be a valid `client_sms_profile_id`
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`.
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
language string Optional Value must be one of the following : "en" or "fr".
allowed_senders string Optional List of all the `allowed_senders` wanted separated by a comma.
notify_name integer Optionally required Value must be alphanumeric string. Required if option "inbound_completed_notification" is selected.
notify_email string Optionally required Value must be alphanumeric string. Required if option "inbound_completed_notification" is selected.
forward_number string Optionally required Value must be a valid phone number of 10 digits. Required if option "enable_forwarding" is selected.
callback_url string Optionally required Must be a valid Webhook. Can contain GET arguments. Details will be sent as JSON in the POST body.
Required if option "enable_callback" is selected.
backup_url string Optional Must be a valid Webhook. Can contain GET arguments. Details will be sent as JSON in the POST body.
Will be called if `callback_url` does not respond.
autoreply_message string Optionally required Value must be alphanumeric string of maximum 160 characters. Required if option "enable_autoreply" is selected.
client_did_id string Optional Value must be a valid `client_did_id`.
options string Required Value must be any of the following comma seperated: "inbound_completed_notification", "outbound_completed_notification", "outbound_failed_notification", "enable_forwarding", "enable_callback", "enable_autoreply" or "enable_callback_retry"
status string Optional Value must be one of the following: "enabled", "disabled" or "deleted"
comments string Optional
Delete SMS profile

Delete a SMS profile from your account.

Request Type: delete_sms_profile

Parameter Type [?] Requirement Description
client_sms_profile_id integer Required Value must be a valid `client_sms_profile_id`.
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)
client_channel_id integer Optional Value must be a valid `client_channel_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_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
mode string Optional Value must be "update" or "create".
(default is update)
client_peer_id
integer Optionally required If mode is "update", value must be a valid `client_peer_id`
proxy_id
integer Optionally required Only available on mode `create`. Value must be a valid `proxy_id`
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
host_type string Required Value must be one of the following: "dynamic" or "static"
(default is NULL)
host string Optional Value must be a valid ip address
port string Optional Value must be a valid port
peer_username string Optionally required Only available on mode `create`. Value must be alphanumeric string from 6 to 32 characters.
username string Deprecated Only available on mode `create`. Value must be alphanumeric string from 6 to 32 characters.
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 Required Value must be one of the following: "global", "privacy", "custom", "device" or "smart"
callerid_type string Optionally Required Required on mode `update`. Value must be one of the following: "rpid", "pid" or "none"
callerid_format string Optionally Required Required on mode `update`. Value must be one of the following: "e164", "unaltered" or "national"
client_callerid_profile_id integer See description Required if callerid_mode is set to "smart". Must be a valid client_callerid_profile_id.
transport string Optionally Required Required when using static IP or ACL `update`. Value must be one of the following: "udp", "tcp", "tls"
codecs enum Optionally Required Required on mode `update`. Value must be one (or more, comma separated) of the following: "g729", "ulaw", "alaw", "g726", "gsm" or "ilbc"
dtmf_mode string Optionally Required Required on mode `update`. Value must be one of the following: "rfc2833", "inband", "info" or "auto"
dnis_mode string Optionally Required Required on mode `update`. Value must be one of the following: "auto", "forced" or "disabled"
(default is auto)
dnis_format string Optionally Required Required on mode `update`. Value must be one of the following: "national" or "e164"
(default is 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 Deprecated 1 = enabled, 0 = disabled
(default is 0)
will set the dnis_mode at forced
enable_notification integer Optional 1 = enabled, 0 = disabled
(default is 0)
simultaneous_calls_limit integer Optional Value must be a number between 0 and 255
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_channel_id integer Optional Value must be a valid `client_channel_id`.
(default is 0)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
client_filter_ids Array Optional Value must be one or more valid client_filter_id.
(default is NULL)
enable_notify_callback integer Optional 1 = enabled, 0 = disabled
(default is 0)
notify_callback_triggers Array Optional Value must be one (or more, comma separated) of the following: "on_create", "on_ring", "on_answer", "on_hangup", "on_test", "on_record" (default is NULL)
notify_callback_url string Optional Value must be a valid Webhook. If this value is changed, we will hit the url and expect an HTTP Code 200. The test hit will have the trigger on_test.
(default is NULL)
register_timeout string Optional Only available on mode `create`. Value must be between 120 and 7200.
progress_timeout string Optionally required Only available on mode `create`. Value must be between 1 and 10.
provisioned_endpoint_id integer Optional Value must be a valid `client_endpoint_id` or one of the following values: 0 = default, 1 = dynamic, 2 = block, 3 = unprovisioned
status string Optionally Required Required on mode `update`. Value must be one of the following: "enabled" or "disabled"
comments string Optional  
Delete peer

Delete a peer from your account.

Request Type: delete_peer

Parameter Type [?] Requirement Description
client_peer_id integer Required Value must be a valid `client_peer_id`.
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`
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
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  
Delete mailbox

Delete a mailbox from your account.

Request Type: delete_mailbox

Parameter Type [?] Requirement Description
client_mailbox_id integer Required Value must be a valid `client_mailbox_id`.
Get Text-to-Speech voice name

Get all available Text-to-Speech (TTS) voice names available

Request Type: get_tts_voice_name
Request Type Added on March 20th 2023
Show Sample XML response
Update Mailbox Greeting

Allows you to create or simply update a mailbox greeting's. It is important to note that this is a POST request.

Request Type: update_mailbox_greeting
Request Type Added on March 20th 2023

Parameter Type [?] Requirement Description
mode string Required Value must be "text_to_speech", "existing_file" or "post_file".
client_mailbox_id
integer Required Value must be a valid `client_mailbox_id`
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
By default if a new media file is create it will be named "greeting_mailbox_{client_mailbox_id}", where client_mailbox_id is the mailbox we are adding the greeting at.
text string Optionally Required Value must be present when the mode is "text_to_speech" and is used to create the new file with the text given.
voice_name string Optionally Required Value must be a valid voice_name for the Text-to-Speech.
By default it is "fr-CA-Standard-A".
client_media_file_id integer Optionally Required Value must be present when the mode is "existing_file" and be a valid `client_media_file_id`.
attachments integer Optionally Required Value must be present when the mode is "post_file" and be a valid file.
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)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_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)
client_queue_ids enum Optional Value(s) must be valid client_queue_id(s) (comma separated).
(default is NULL)
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)
announce_media_file_id integer Optionally required Required if `announce_caller` is set. Must be between a valid `announce_media_file_id`.
send_dtmf string Optional Must be valid DTMF tones (0-9,a,b,c,d,w and W).
voice_language string Optional Value must valid one of the following: "en", "fr". Default is account preferred language.
confirm_media_file_id integer Optional >If specified alongside the `confirm_required` option, will play this message when asking the callee to confirm answering.
client_mailbox_id integer Optional Value must valid `client_mailbox_id`.
enable_voicemail integer Optional 1 = enabled, 0 = disabled
(default is 0)
enable_parking integer Optional 1 = enabled, 0 = disabled
(default is 0)
options Array Optional Value must be one or more of the following : "confirm_required", "announce_caller" (default is NULL).
dnis_rewrite digits [10] Optional Value must be a valid DID number.
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`
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 Subaccounts details

You can get the details and settings of your Subaccounts by specifying the `client_subaccount_id`. If you do not provide the value, the details for all Subaccounts will be returned.

Request Type: get_subaccounts

Parameter Type [?] Requirement Description
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
client_brand_id integer Optional Value must be a valid `client_brand_id`.
(default is NULL)
status enum Optional Value must be one (or more, comma separated) of the following: "enabled", "disabled" or "deleted"
(default is NULL)
get_associations bool Optional Value must be one of the following: "1" or "0"
(default is 0). This will return the list of ids of peer, did, extension and mailbox associated to the client_subaccount.
Show Sample XML response
Update Subaccount

Allows you to create or simply update a subaccount.

Request Type: update_subaccount

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_subaccount_id
integer Optionally required If mode is "update", value must be a valid `client_subaccount_id`
client_brand_id
integer Optional Value must be a valid `client_brand_id`.
If `client_brand_id` is not provided, default brand will be assumed.
custom_id string Optional
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
call_limit integer Optional Value must be a number between 0 and 999
allow_international_call string Optional Value must be one of the following: "yes" or "no" (default is "no")
international_call_limit integer Optional (default is 1)
require_international_nip string Optional Value must be one of the following: "yes" or "no". (default is "no")
international_nip string Optional Value must be a number between 6 and 8 character. More than one value can be used separated by comma. (default is "NULL")
multi_tenancy_mode string Required Value must be one of the following: "disabled", "global", "self" or "shared"
multi_tenancy_subaccount_id string Optionally required If "multi_tenancy_mode" is shared must be a valid `client_subaccount_id`
organization string Optional
organization_type string Optional Value must be one of the following: "personal" or "business"
client_profile string Optional Value must be one of the following: "undefined", "residential_client", "commercial_client", "callcenter_client" or "internal" (default is "undefined")
voice_language string Optional Value must be one of the following: "en" or "fr" (default is NULL)
notification_language string Optional Value must be one of the following: "en" or "fr" (default is NULL)
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.
client_moh_profile_id string Optional Value must must be a valid `client_moh_profile_id` (default is NULL)
default_provisioned_endpoint_id string Optional Value must must be a valid `provisioned_client_did_id` (default is NULL)
options Array Optional Value must be one or more of the following : "subaccount_override_enabled", "enable_billing_module", "enable_billing_notification", "disable_411_access", "disable_public_service_access". (default is NULL)
status string Required Value must be one of the following: "enabled", "disabled" or "deleted"
comments string Optional
Update Subaccount Associations

You can update the associations of a subaccount with this request type.

Request Type: update_subaccount_associations

Parameter Type [?] Requirement Description
client_subaccount_id
integer Required Value must be a valid `client_subaccount_id`
associated_peers enum Optional Only the list of all the given ids will be saved, erasing missing values.
Value must be one (or more, comma seperated) valid `client_peer_id`
associated_dids enum Optional Only the list of all the given ids will be saved, erasing missing values.
Value must be one (or more, comma seperated) valid `client_did_id`
associated_extensions enum Optional Only the list of all the given ids will be saved, erasing missing values.
Value must be one (or more, comma seperated) valid `client_extension_id`
associated_fax_profiles enum Optional Only the list of all the given ids will be saved, erasing missing values.
Value must be one (or more, comma seperated) valid `client_fax_profiles`
associated_sms_profiles enum Optional Only the list of all the given ids will be saved, erasing missing values.
Value must be one (or more, comma seperated) valid `client_sms_profiles`
associated_mailboxes enum Optional Only the list of all the given ids will be saved, erasing missing values.
Value must be one (or more, comma seperated) valid `client_mailbox_id`
Update a Subaccount Address

Allows you to create or simply update an address for the subaccount.

Request Type: update_subaccount_address

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_subaccount_id
integer Required Value must be a valid `client_subaccount_id`
client_address_id
integer Optionally required If mode is "update", value must be a valid `client_address_id`
type string Optional Value must be one of the following: "billing"
There can be only one subaccount with an address of the type "billing".
(default is "billing")
box_number string Optional
civic_number integer Required Value must be a number.
street string Required Value must be alphanumeric string.
unit_number integer Required Value must be a number.
city string Required Value must be alphanumeric string.
country_id integer Required Value must be a valid `country_id`
state_id string Optionally required If country_id is "38" or "223", must be a valid `state_id`.
state_other string Optionally required If country_id is not is "38" or "223", must be alphanumeric string.
postal_code string Required Must be a valid `postal_code`.
precision string Optionally required
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 call director profiles

If you wish to get details of a call director profile, you simply have to pass the `client_director_profile_id`. If no additional parameter is specified, the complete list of peers will be returned.

Request Type: get_call_director_profiles

Parameter Type [?] Requirement Description
client_director_profile_id integer Optional Value must be a valid `client_director_profile_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
Show Sample XML response
Update Call director profile

Allows you to create or simply update a Call director profile.

Request Type: update_call_director_profile

Parameter Type [?] Requirement Description
preserve_missing_data
boolean Optional This will allow you to modify only the provided fields when updating an entry (default is FALSE)
mode string Optional Value must be "update" or "create".
(default is update)
client_director_profile_id
integer Optionally required If mode is "update", value must be a valid `client_director_profile_id`
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
action
array At least 1 required
Parameter Type [?] Requirement Description
usage_type
string Required Value must be one of the following: 'forward', 'peer', 'sip_uri'
offset
integer Required When to start this action (in seconds). Must be between 0 and 115 and an increment of 5.
duration
integer Required How long to take this action (in seconds). Max total 120. Must be betweeb 5 and 120.
client_peer_id
integer Optionally required Required if usage_type is 'peer'. Must be a valid `client_peer_id`
forward_number
digits Optionally required Required if usage_type is 'forward'. Must be a valid phone number.
sip_uri
string Optionally required Required if usage_type is 'sip_uri'. Must be a valid SIP uri.
announce_media_file_id integer Optionally required Only used for `usage_type` 'forward'.
Required if `announce_caller` is set. Must be between a valid `announce_media_file_id`.
send_dtmf string Optional Only used for `usage_type` 'forward'.
Must be valid DTMF tones (0-9,a,b,c,d,w and W).
confirm_media_file_id integer Optional Only used for `usage_type` 'forward'.
Value must be a valid client_media_file_id.
(default is 0)

If specified alongside the `confirm_required` option, will play this message when asking the callee to confirm answering.
options Array Optional Only used for `usage_type` 'forward'.
Value must be one or more of the following : "confirm_required", "announce_caller" (default is NULL).
comments string Optional
example:
action[0][usage_type]=forward&action[0][forward_number]=5145555555&action[0][offset]=0&action[0][duration]=60
status string Optional Value must be one of the following: "enabled" or "disabled"
comments string Optional  
Delete Call Director Profile

Delete a Call Director Profile from your account.

Request Type: delete_call_director_profile

Parameter Type [?] Requirement Description
client_director_profile_id integer Required Value must be a valid `client_director_profile_id`.
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
plan_id integer Optional Value must be a valid `plan_id`.
plan_groups_id integer Optional Value must be a valid `plan_group_id`.
Show Sample XML response
Get Proxies

Get the list of available proxies.

Request Type: get_proxies

Parameter Type [?] Requirement Description
proxy_id integer Optional Value must be a valid `proxy_id`.
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
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_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
result_limit integer Optional Value must be between 1 and 1000
(default is 1000)
result_offset integer Optional Value must be a valid number
(default is NULL)
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 Optional 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 Deprecated Value must be a valid `first_name`.
last_name string Deprecated Value must be a valid `last_name`
full_name string Required Value must be a string between 2 and 32 characters.
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 Deprecated Value must valid one of the following: "en", "fr". Default is account preferred language. Ignored outside of Canada.
This parameter has been replaced by e911_language and will eventually be removed.
e911_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`
rate_provider_id integer Optional Must be a valid `rate_provider_id`
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
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`
Get whitepages (411)

Get the list of current whitepages (411) available along with their included services.

Request Type: get_whitepages

Parameter Type [?] Requirement Description
provision_status enum Optional Value must be one (or more, comma seperated) of the following: "pending", "activated", "rejected" or "removed"
(default is all status)
status enum Optional Value must be one (or more, comma seperated) of the following: "enabled" or "deleted"
(default is "enabled")
Show Sample XML response
Update whitepages (411) directory listing.

Update the provisioned address for a whitepages (411) directory listing.

Request Type: update_whitepages

Parameter Type [?] Requirement Description
phone_number integer Required Value must be a valid phone number of 10 digits. ( No space or - symbol )
type string Required Must be one of the following : "business", "residential", "government"
sort_word string Required Value must be between 2 and 30 characters. Characters allowed : alphanumeric (including accents), space, dash, single-quote.
Errors will refer to this field as `first_name`
sub_word string Required Value must be between 2 and 106 characters. Characters allowed : alphanumeric (including accents), space, dash, single-quote.
Errors will refer to this field as `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`
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`
Delete whitepages (411) directory listing

Delete the provisioned address for a whitepages (411) directory listing.

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

Request Type: delete_whitepages

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_411_listing_id integer Optionally required Value must be a valid `client_411_listing_id`
Report call issue

Report an issue for a specific call.

Request Type: report_call_issue

Parameter Type [?] Requirement Description
call_hash string Required Value must be a 32 characters alphanumeric Call Hash referencing the last call previously returned by your last request made with `get_calls`.
issue_type_id int Required Value must be an integer referencing and issue type returned by a request made with `get_issues_types`.
kayako_ticket_id string Optional Value must have the following format: 'AAA-999-99999'.
comments string Optional  
Get Issues details

Get reported call issues.

Request Type: get_call_issues

Parameter Type [?] Requirement Description
call_hash string Required Value must be a 32 characters alphanumeric call hash. (default is NULL)
call_issue_id int Required Value must be a valid `call_issue_id`. (default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
Show Sample XML response
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
mode string Optional Value must be either 'latest' or 'unresolved'.
(default is latest)
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
Get channels details

Get the full list of channels or you can get a single entry by providing `client_channel_id`. System row represent all channels the account possess throught plans and services.

Request Type: get_channels

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

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

Request Type: update_channel

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_channel_id
integer Optionally required If mode is "update", value must be a valid `client_channel_id`
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
quantity_inbound integer Required Value must be a number between 0 and 999 (inclusively).
quantity_outbound integer Required Value must be a number between 0 and 999 (inclusively).
quantity_bidirectional integer Required Value must be a number between 0 and 999 (inclusively).
Delete channel

Delete a channel group from your account.

Request Type: delete_channel

Parameter Type [?] Requirement Description
client_channel_id integer Required Value must be a valid `client_channel_id`.
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

language", "send_dtmf", "announce_media_id", "announce_media_path", "confirm_required", "confirm_media_id", "confirm_media_path", "retries", "accept_key", "reject_key"
Parameter Type [?] Requirement Description
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`
source_type string Deprecated Use `sources[0][type]` instead.
source digits [10] alphanum [6-16] Deprecated Use `sources[0][value]` instead.
destination_type string Deprecated Use `destinations[0][type]` instead.
destination digits [10] alphanum [6-16] Deprecated Use `destinations[0][value]` instead.
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 must be a valid `Caller ID number`.
(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.
sources[n][type] // destinations[n][type] integer Optional 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.
If type is "uri" then value must be a valid SIP URI.
sources[n][value] // destinations[n][value] integer Optional 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.
If type is "uri" then value must be a valid SIP URI.
sources[n][callerid_name] // destinations[n][callerid_name] string [3-15] Optional Value must be alphanumeric string from 3 to 15 characters.
(defaults to provided `callerid_name`)
sources[n][callerid_number] // destinations[n][callerid_number] string [10-15] Optional Value must be a valid `CallerID Number`.
(default to provided `callerid_number`)
sources[n][language] // destinations[n][language] string (en|fr) Optional Language used for default prompts.
sources[n][send_dtmf] // destinations[n][send_dtmf] string Optional DTMF sequence to send
sources[n][announce_media_id] // destinations[n][announce_media_id] integer Optional Media ID of annoucement
sources[n][confirm_required] // destinations[n][confirm_required] boolean [0|1] Optional Call must be confirmed to be considered answered

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

sources[n][confirm_media_id] // destinations[n][confirm_media_id] integer Optional Media ID of call confirmation message
sources[n][retries] // destinations[n][retries] integer Optional Number of retries for call confirmation
sources[n][accept_key] // destinations[n][accept_key] integer Optional Key to press to accept call
(default is 1)
sources[n][reject_key] // destinations[n][reject_key] integer Optional Key to press to reject call
(default is 2)
Voicemail Broadcast

Experimental feature for the sole purpose of leaving a voicemail in a mailbox for a given destination number.

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

Note: Recordings of 2 seconds or less are automatically deleted.
Note: Both calls will be imported in the call history if `fork_call` is used.

Request Type: voicemail_broadcast

Parameter Type [?] Requirement Description
destination_number digits [10] Required Must be valid phone number of at least 10 digits.
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`)
privacy integer Optional Enable privacy for this call. Please note that a valid callerid_number is required


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

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)
client_media_file_id string Optionally required Media file ID used for playback to voice mailbox.
Must be provided unless `media_url` is set.
(default is NULL)
media_url string Optional Use a media file located in the cloud.
Value must be a valid URL.
(default is NULL)

voicemail_detect integer Optional Works great with `fork_call`. Automatically start playback if voicemail tone is detected.

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

fork_call integer Optional Works great with `voicemail_detect`, will make two calls to destination to force voicemail to pick-up and automatically cancel second call.

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

pre_dtmf string Optional DTMF sequence to play once call is answered, before playback.
Valid DTMF are : 0 1 2 3 4 5 6 7 8 9 A B C D # * w W
post_dtmf string Optional DTMF sequence to play once call is answered, after playback.
Valid DTMF are : 0 1 2 3 4 5 6 7 8 9 A B C D # * w W
dtmf_duration integer Optional Change duration of DTMF tones.
Value must be between 100 and 1500 (inclusively)
(default is 500)
notify_callback_triggers string Optionally required Value must be one (or more, comma separated) of the following: "on_create", "on_ring", "on_answer", "on_hangup", "on_record"
(default is NULL)

Required if `notify_callback_url` is set.
notify_callback_url string Optionally required Value must be a valid Webhook.
(default is NULL)

Required if `notify_callback_triggers` is set.
meta_data string Optional Any value is accepted.
Get list of reseller transactions

Get a full list of all reseller transactions.

Request Type: get_resellers_transactions

Parameter Type [?] Requirement Description
reseller_transaction_id integer Optional Must be a valid `reseller_transaction_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
date_from date Optional Value must be a valid date. Based on `date_applied`
(default is NULL)
date_to date Optional Value must be a valid date. Based on `date_applied`
(default is NULL)
Show Sample XML response
Get list of reseller invoices

Get a full list of all reseller invoices.

Request Type: get_resellers_invoices

Parameter Type [?] Requirement Description
reseller_invoice_id integer Optional Must be a valid invoice `reseller_invoice_id`.
(default is NULL)
web_key string Optional Must be a valid invoice `web_key`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
date_from date Optional Value must be a valid date. Based on `date_applied`
(default is NULL)
date_to date Optional Value must be a valid date. Based on `date_applied`
(default is NULL)
Show Sample XML response
Get queues details

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

Request Type: get_queues

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

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

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

Request Type: update_queue

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_queue_id integer Optionally required If mode is "update", value must be a valid `client_queue_id`
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Required Value must be alphanumeric string from 2 to 60 characters.
comments string Optional  
client_moh_profile_id integer Optional Value must be a valid `client_moh_profile_id`.
(default is 0)
max_wait_time integer Optional Value must be between 10 and 7200.
(default is 300)
max_wait_time_no_agent integer Optional Value must be between 30 and 600.
(default is 90)
progressive_ring_delay integer Optional Value must be between 5 and 300.
(default is 10)
discard_abandoned_delay integer Optional Value must be between 300 and 86400.
(default is 900)
max_no_agent integer Optional Value must be between 0 and 99.
(default is 0)
tier_escalate_delay integer Optional Value must be between 30 and 3600.
(default is 120)
datetime_suspended_until string Optional Value must be a valid datetime in format 'yyyy-mm-dd H:i:s'
(default is 0000-00-00 00:00:00)
agents string Optional Value must be a list of agent ids comma seperated.
options string Optional Value must be any of the following comma seperated: "enable_resume_abandoned", "enable_tiers_escalation", "enable_escalate_no_agent" or "enable_escalate_multiply_delay"
status string Optional Value must be one of the following: "enabled" or "disabled"
Get queue agents details

If you wish to get details of a specific queue agent, you simply have to pass the `client_queue_agent_id`. If no additional parameter is specified, the complete list of queue agents will be returned.

Request Type: get_queue_agents

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

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

Request Type: update_queue_agent

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_queue_agent_id integer Optionally required If mode is "update", value must be a valid `client_queue_agent_id`
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Required Value must be alphanumeric string from 2 to 60 characters.
comments string Optional  
client_peer_id integer Optional Value must be a valid `client_peer_id`.
(default is 0)
client_director_profile_id integer Optional Value must be a valid `client_director_profile_id`.
(default is 0)
client_schedule_id integer Optional Value must be a valid `client_schedule_id`.
(default is NULL)
ring_delay integer Optional Value must be between 5 and 120.
(default is 10)
wrap_up_delay integer Optional Value must be between 0 and 600.
(default is 15)
on_busy_delay integer Optional Value must be between 0 and 3600.
(default is 120)
on_reject_delay integer Optional Value must be between 0 and 3600.
(default is 300)
on_unanswered_delay integer Optional Value must be between 0 and 3600.
(default is 30)
max_unanswered integer Optional Value must be between 0 and 99.
(default is 0)
agent_status string Optional Availability of the agent in the queue system. Value must be one of the following: "online" , "offline" , "break"or "automatic"
(default is null)
status string Optional Value must be one of the following: "enabled" or "disabled"
Get Callerid Profiles Details

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

Request Type: get_callerid_profiles

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

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

Request Type: update_callerid_profile

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_callerid_profile_id integer Optionally required If mode is "update", value must be a valid `client_callerid_profile_id`
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
callerid_name string Optional Value must be alphanumeric string from 2 to 15 characters.
client_did_ids enum Optional Value(s) must be valid client_did_id(s) (comma separated).
default_client_did_id integer Optional Value must be a valid `client_did_id`.
callerid_number integer Optional Value must be a valid phone number of 10 digits.
privacy integer Optional Value must be one of the following: "enable", "keep" or "disable"
status string Required Value must be one of the following: "enabled" or "disabled"
comments string Optional  
purge_conditions integer Optional If value is set to 1 it will remove all the callerid profile datas not listed in the conditions_data
conditions_data JSON Optional
Parameter Type [?] Requirement Description
client_callerid_profile_data_id
integer Optionally required Value used to edit an existing condition. Must be a valid `client_callerid_profile_data_id`.
callerid_name
string Optional If added will use the callerid_name provided as the callerId name.
client_did_id
integer Optional If added will use the client_did_id provided as the callerId number.
callerid_number
integer Optional If added will use the callerid_number provided as the callerId number.
privacy
enum Optional Value must be one of the following: "enable", "keep" or "disable". Default is "keep".
country_id
integer Optional Value must be a valid country_id.
state_id
integer Optional Value must be a valid state_id.
ratecenter_id
integer Optional Value must be a valid ratecenter_id.
radius_distance
integer Optional Value is a distance in km between 10 and 1000.
source_number
integer Optional Value must be between 1 and 10 digits.
source_regexp
string Optional Value must be a valid regexp.
destination_number
integer Optional Value must be between 1 and 10 digits.
destination_regexp
string Optional Value must be a valid regexp.
match_methods
enum Optional Value must be one (or more, comma separated) of the following: "local_to_destination", "radius_from_destination", "source_number_match", "destination_number_match", "region", "source_regexp" or "destination_regexp".
order_index
integer Optional Value used to set the priority of the condition.
comments
string Optional
example:
conditions_data=[{"client_callerid_profile_data_id":"1234","callerid_name": "NewName"},{"callerid_name": "NewCondition", "client_did_id": "12345"}]
Get IVR profiles details

If you wish to get details of a specific IVR profile, you simply have to pass the `client_ivr_profile_id`. If no additional parameter is specified, the complete list of IVRs will be returned.

Request Type: get_ivr_profiles

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

You can update the configuration of an IVR profile with this request type.

Request Type: update_ivr_profile

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_ivr_profile_id integer Optionally required If mode is "update", value must be a valid `client_ivr_profile_id`
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Required Value must be alphanumeric string from 2 to 60 characters.
default_language string Optional Value must be one of the following: ""(empty), "en" or "fr"
pre_ivr_extension integer Optional Value must be a valid `client_extension_id`.
(default is 0)
pre_ivr_delay string Optional Value must be one of the following: "2", "5", "10", "15", "20", "25" or "30" (default is 10)
client_office_hour_id integer Optional Value must be a valid `client_office_hour_id`.
(default is 0)
client_moh_profile_id integer Optional Value must be a valid `client_moh_profile_id`.
(default is 0)
options string Optional Value must be any of the following comma seperated: "enable_directory","disable_moh"
status string Required Value must be one of the following: "enabled" or "disabled"
comments string Optional  
[raw_metadata] see doc see doc Additional information for the metadata can be found here.
Get Schedules
Get details for schedules (office hours).
Request Type: get_schedules

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

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

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

Request Type: update_schedule

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is 'update')
client_schedule_id integer Optionally required If mode is "update", value must be a valid `client_schedule_id`
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is 0)
friendly_name string Required Value must be alphanumeric string from 2 to 60 characters.
comments string Optional  
time_zone_id integer Optional Value must be a valid `time_zone_id`.
(default is based on account preferences)
range_date string Optional Value must be one of 'daily', 'weekly', 'custom'.
(default is 'daily')
shift_start_date string Optional Value must be between a valid date in format "YYYY-MM-DD".
(default is current date)
business_hours json Optional Note: Not yet fully implemented, only month-day exceptions are accepted.
Example JSON string:
{"month4":{"day22":[{"start":"00:00:00","end":"10:30:00","type":"exception"}]}}
shift json/array Optional
Parameter Type [?] Requirement Description
status
string Required Value must be one of the following: 'one', 'off'
days
integer Required Value must be a number of days
Example URI array:
shift[0][status]=on&shift[0][days]=2&shift[1][status]=off&shift[1][days]=2

Example JSON string:
[{"status":"on","days":"2"},{"status":"off","days":"2"}]
status string Optional Value must be one of the following: "enabled" or "disabled"
Get Storage statistics
Gather statistical information about storage stats for given period.
Request Type: get_storage_stats

Parameter Type [?] Requirement Description
date_from date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Max date range between `date_to` and `date_from` is 12 months.
(default is today)
date_to date Optional Value must be a valid date formatted as "YYYY-MM-DD".
Max date range between `date_to` and `date_from` is 12 months.
(default is today)
client_subaccount_ids enum Optional List of all the `client_subaccount_id` wanted separated by a comma.
Max 10 `client_subaccount_id`.
(default is main_account and whole_account (main_account + subaccounts))
storage_types enum Optional List of all the client storage types wanted separated by a comma.
(default is NULL)
Show Sample XML response with no subaccount_ids specified.
Show Sample XML response with subaccount_ids specified.
Get Media Files
Get details for media failes.
Request Type: get_media_files

Parameter Type [?] Requirement Description
client_media_file_id integer Optional Search for a specific media file.
Value must be a valid `client_media_file_id`.
(default is NULL)
client_media_folder_id integer Optional Search for files in a specific folder.
Value must be a valid `client_media_folder_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
Show Sample XML response
Get Devices

Get all available autoprovision devices

Request Type: get_devices

Parameter Type [?] Requirement Description
make string Optional Value must be a valid `make`.
(default is NULL)
Show Sample XML response
Get Device Endpoint (Autoprovision)

If you wish to get details of a device endpoint, you simply have to pass the `client_device_endpoint_id`. If no additional parameter is specified, the complete list of endpoints will be returned.

Request Type: get_device_endpoints
Request Type Added on February 20th 2023

Parameter Type [?] Requirement Description
client_device_endpoint_id integer Optional Value must be a valid `client_device_endpoint_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
device_mac string Optional Value must be a valid `device_mac`.
(default is NULL)
device_id integer Optional Value must be a valid `device_id`.
(default is NULL)
Show Sample XML response
Update Device Endpoint (Autoprovision)

Allows you to create or simply update a Device Endpoint (Autoprovision).

Request Type: update_device_endpoint
Request Type Added on February 20th 2023

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
client_device_endpoint_id
integer Optionally required If mode is "update", value must be a valid `client_device_endpoint_id`
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`.
friendly_name string Optional Value must be alphanumeric string from 2 to 32 characters.
device_id
integer Required Value must be a valid `device_id` see Get devices.
device_name string Optional
client_peer_ids string Optional List of all the `client_peer_id` used separated by a comma. If the device supports label can also include labels using the `|` symbol (eg: 1234|Mike Phone,5678|Barbara)
client_extension_id integer Optionally required Value must be a valid `client_extension_id`
client_mailbox_id integer Optionally required Value must be a valid `client_mailbox_id`
device_mac string Optional Value must be a valid mac address, we support (AABBCCDDEE or AA:BB:CC:DD:EE)
serial_number string Optional Device Serial Number
timezone_id string Optional Value must be a valid `timezone_id`.
admin_password string Optional
phone_password string Optional
language string Optional Value must be one of the following: "fr" or "en"
is_time_format24h boolean Optional Value must be one of the following: "1" or "0"
is_vlan_enabled string Optional Value must be one of the following: "1" or "0"
vlan number Optional If Vlan is enabled put the Vlan ID here
call_waiting string Optional Value must be one of the following: "active" or "inactive"
call_forwarding string Optional Value must be one of the following: "allow" or "disallow"
is_vlan_enabled string Optional Value must be one of the following: "allow" or "disallow"
button_config JSON Optional The button config in JSON format.
Example : `{"1":{"feature":"presence","label":"Steve Ruck","line":"1","feature_value":"dnis_test"},"2":{"feature":"speed_dial","label":"PARK","line":"3","feature_value":"5141234568"}}`
Detailed documentation will be provided soon, in the meantime I suggest building it through the client section and getting the results via Get device endpoints (Autoprovision) and go from there.
status string Optional Value must be one of the following: "enabled", "disabled" or "deleted"
comments string Optional
Delete Device Endpoint (Autoprovision)

Delete a Device Endpoint from your account.

Request Type: delete_device_endpoint

Parameter Type [?] Requirement Description
client_device_endpoint_id integer Required Value must be a valid `client_device_endpoint_id`.
Get 3cx Server Details

If you wish to get details of a 3cx server, you simply have to pass the `pbx3cx_server_id`. If no additional parameter is specified, the complete list of servers will be returned.

Request Type: get_3cx_servers
Request Type Added on January 30th 2024

Parameter Type [?] Requirement Description
pbx3cx_server_id integer Optional Value must be a valid `pbx3cx_server_id`.
(default is NULL)
client_subaccount_id integer Optional Value must be a valid `client_subaccount_id`.
(default is NULL)
friendly_name string Optional Value must be a valid string.
(default is NULL)
server_fqdn string Optional Value must be a valid string.
(default is NULL)
license_key string Optional Value must be a valid string.
(default is NULL)
level integer Optional Value must be a valid service level (1, 2 or 3).
(default is NULL)
Show Sample XML response
Update a 3cx Server

Allows you to create or simply update a 3cx Server.

Request Type: update_3cx_server
Request Type Added on January 30th 2024

Parameter Type [?] Requirement Description
mode string Optional Value must be "update" or "create".
(default is update)
pbx3cx_server_id
integer Optionally required If mode is "update", value must be a valid `pbx3cx_server_id`
client_subaccount_id
integer Optional Value must be a valid `client_subaccount_id`.
friendly_name string Required Value must be alphanumeric string from 2 to 32 characters.
server_port integer Optional Value must a valid port (default 443).
level string Optional Value must be one of the following service level values: "1" or "2" or "3"
server_fqdn string Optional Value must be a valid FQDN.
is_connection_allowed boolean Optional Value must be one of the following: "1" or "0" (default 0).
If set will connect to the server using the "server_name" and "server_password" for synchronisation and maintenance.
Required for the following options : 'sync_calls','sync_recording_media','sync_voicemail_media','sync_backups','auto_renew_ssl'
Required for "monitoring_status" enabled.
server_name string Optionally Required Value must be alphanumeric. Required for "is_connection_allowed".
server_password string Optionally Required Value must be alphanumeric. Required for "is_connection_allowed".
enable_fetch_license_expiration boolean Optional Value must be one of the following: "1" or "0" (default 0).
If set will use either the 3cx Portal or a direct server connection to get information on the server (Expiration, Licence Key, Product Type, etc..)
license_key string Optional Value must be a valid 3cx License Key.
license_expiration date Optional Value must be a valid date in "Y-m-d" format.
product_edition string Optional Value must be one of the following: 'Professional','Standard','Enterprise','Startup'
product_simultaneous_calls string Optional Value must be one of the following: '4','8','16','24','32','48','64','96','128','192','256','512','1024'
options string Optional Value must be any of the following comma seperated: 'sync_calls', 'sync_recording_media', 'sync_voicemail_media', 'backup_includes_voicemails', 'sync_backups', 'backup_includes_templates', 'encrypt_backup', 'auto_renew_ssl'
encrypt_backup_password string Optionally Required Value must be alphanumeric. Required for "encrypt_backup".
backup_frequency string Optional Value must be one of the following: '1_day','3_day','1_week','2_week','1_month','3_month' (default 3_day)
backup_retention string Optional Value must be one of the following: 'none', '1_day','3_day','1_week','2_week','1_month','3_month' (default 3_day)
call_retention string Optional Value must be one of the following: 'none','1_week','1_month','3_month','6_month','1_year','2_year','3_year','5_year','8_year','10_year' (default 3_year)
dns_service string Optional Value must be one of the following: 'dns_cloudns','dns_cf'. Please see FAQ for more details.
auth_type string Optional Value must be one of the following: 'account','subaccount'. Please see FAQ for more details.
Required for 'dns_cloudns'
auth_id string Optional Value must be alphanumeric. Please see FAQ for more details.
Required for 'dns_cloudns'
auth_password string Optional Value must be alphanumeric. Please see FAQ for more details.
Required for 'dns_cloudns'
certificate_token string Optional Value must be alphanumeric. Please see FAQ for more details.
Required for 'dns_cf'
monitoring_status string Optional Value must be one of the following: "enabled" or "disabled"
subscribed_monitoring string Optional Value must be one of the following: 'system','trunks','services','callflows','sip_test','call_test','system_additional','voicemail','backup','ssl'
alert_status string Optional Value must be one of the following: "enabled" or "disabled"
subscribed_alerts string Optional Value must be one of the following: 'connectivity','system','trunks','services','callflows','sip_test','call_test','system_additional','voicemail','backup','ssl'
Services must be active in 'subscribed_monitoring' for alerting to work.
alert_recipients string Optional Coma separated list of email recipients for all alerts
status string Optional Value must be one of the following: "enabled", "disabled" or "deleted"
comments string Optional
Delete a 3CX Server

Delete a 3cx Server from your account.

Request Type: delete_3cx_server
Request Type Added on January 30th 2024

Parameter Type [?] Requirement Description
pbx3cx_server_id integer Required Value must be a valid `pbx3cx_server_id`.
Error types

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

Global
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.
requests_soft_limit_reached The limit of requests has been reached. Further requests may be denied
requests_hard_limit_exceeded The limit of requests allowed has been exceeded. Request is denied.
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.
Dispatch Call
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.
Get Calls
Error type Description
direction_invalid Direction is invalid.
call_hash_invalid Call Hash is invalid.
Get Rates
Error type Description
code_invalid Code is invalid.
search_parameters_required Search parameters are required.
Report Call Issue
Error type Description
call_hash_invalid Call Hash is invalid.
call_issue_id_invalid Call Issue ID is invalid.
Get Recordings
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.
Process Payment
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.
Update DID
Error type Description
forward_number_used_by_did Forward number already in use.
Update Extension
Error type Description
extension_already_in_use Extension is already in use.
extension_invalid Extension is invalid.
extension_required Extension is required.
Update Mailbox
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.
Update Peer
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.
e911 Errors
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.
Order new dids
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 [JSON Format is preferred].
(default is NULL)
Applicable request types : update_did, update_peer, update_mailbox, update_extension, update_subaccount, update_port_request.
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, get_fax_profiles, get_sms_profiles, get_subaccounts, get_port_requests.
Changelog
2024-02-23
2024-01-30
2024-01-18
2023-12-18
2023-12-08
2023-08-28
2023-06-20
2023-06-15
2023-03-20
2023-02-20
2023-02-07
2023-01-31
2023-01-23
2022-12-20
2022-11-01
2022-09-07
2022-08-08
2022-06-10
2022-02-07
2022-02-01
2022-01-14
2021-11-02
2021-10-25
2021-10-15
2021-10-06
2021-09-20
2021-05-28
2021-05-14
2021-04-12
2021-03-15
2021-03-01
2021-01-18
2020-12-22
2020-11-24
2020-10-23
2020-10-13
2020-10-09
2020-10-07
2020-10-05
2020-09-23
2020-08-24
2020-08-18
2020-08-13
2020-08-13
2020-08-03
2020-06-17
2020-06-01
2020-05-21
2020-05-19
2019-12-02
2019-08-16
2019-07-08
2019-06-06
2019-05-30
2019-05-15
2018-12-13
2018-11-28
2018-11-22
2018-11-14
2018-10-11
2018-10-04
2018-09-25
2018-09-19
2018-09-12
2018-09-04
2018-08-21
2018-08-14
2018-07-26
2018-05-24
2018-05-09
2018-03-26
2018-03-13
2018-01-09
2017-12-19
2017-11-22
2017-10-23
2017-09-11
2017-09-01
2017-08-22
2017-08-16
2017-08-02
2017-07-31
2017-07-24
2017-07-17
2017-07-12
2017-07-10
2017-07-10
2017-05-12
  • Added : update_did added `notification_callback_url`, `notification_callback_triggers` parameters and the `enable_notify_callback` option.
  • Added : update_peer added `notification_callback_url`, `notification_callback_triggers` and `enable_notify_callback` parameters.
  • 2017-05-12
    2017-05-04
    2017-04-10
    2017-03-31
    2017-01-30
    2016-11-29
    2016-11-29
    2016-11-28
    2016-11-21
    2016-10-19
    2016-10-17
    2016-10-14
    2016-10-12
    2016-10-04
    2016-08-22
    2016-08-15
    2016-02-26
    2016-02-01
    2016-01-19
    2015-11-09
    2015-06-15
    2015-06-01
    2015-05-07
    2015-04-21
    2015-04-17
    2015-04-01
    2015-03-30
    2015-02-25
    2015-02-24
    2015-02-18
    2015-02-09