Switchvox Extend API
- Kelli Higdon
About
The Extend API methods let you query information from Switchvox.
Extend is a an XML-based API. You may want to use this Sample JavaScript Library.
Connect to the Core Interface
The Core Interface is an XML web service that uses basic authentication for authorization. You pass in XML requests and the Core Interface passes back an XML response.
The Core Interface can be accessed through an easy URL:
https://YOUR.PBX.COM/xml
Test Your Connection
To see if you can connect to your Switchvox using the Extend Core API, type the above URL into your browser.
The API uses basic authentication, and requires you to be authenticated as an extension-user (or as 'admin' or another administrator). If you have recently logged into Switchvox, then you have already been authenticated and have the proper cookies set. If you are not logged in, then you will see the following prompt. (Read more about Authentication.)
Log In
If you type in the username 'admin' and your admin password, then you can use all of the functionality of the API.
If you use another administrator account, then the access levels for that account apply when you use the API. For example, if you have read-only access to 'Manage Extensions,' then you can use switchvox.extensions.getInfo, but you cannot use switchvox.extensions.phones.bulk.upload.
If you use an extension and its password, then you can only use the 'users' functionality of the API, and the tasks you do will apply to that extension.
The XML Response
NOTE: Extend is a an XML-based API. You may want to use this Sample JavaScript Library.
After you enter a valid username and password, Switchvox returns an XML response to your browser. The response will most likely contain an error that your request XML was empty, but that is fine because we were just testing for connectivity. If you didn't get any response, you might need to check your firewall or the Access Control section on your Switchvox.
Sample XML response:
Pick Your Method & Parameters
First pick which method you want to run. As an example, we have chosen "switchvox.extension.search". Every single request is encased in the parent tag "request" and the method is an attribute of that tag:
<request method="switchvox.extension.search">
</request>
This XML is started, but now we need to add parameters. Below are all the possible parameters for the method "switchvox.extensions.search".
Name | Required | Type | Default | Description |
min_extension | optional | string |
| Minimum extension number. |
max_extension | optional | integer |
| Maximum extension number. If both min/max extension is provided, the max must be greater than the min. |
extension_types | optional | string |
| A list of extension types to filter by. See Extension Types for a list of possible values. |
min_create_date | optional | date |
| Minimum creation date of extension. |
max_create_date | optional | date |
| Maximum creation date of extension. |
sort_field | optional | string | number | The field on which to sort the returned extensions. |
sort_order | optional | string | ASC | The order in which to sort returned extensions. Possible values: ASC and DESC. |
items_per_page | optional | integer | 50 | Number of extensions to return per page. |
page_number | optional | integer | 1 | The page number of extensions to return. |
For this example, I want a list of all extensions between extension 100 and 200 and I only want extensions that are either an ivr or a call_queue.
So first we need to create the parameters parent tag that will enclose our parameter list:
<request method="switchvox.extensions.search">
<parameters>
</parameters>
</request>
Next we need to create a tag for each parameter we want to send, and enclose the value of each parameter between starting and closing tags:
<request method="switchvox.extensions.search">
<parameters>
<min_extension>100</min_extension>
<max_extension>200</max_extension>
<extension_types>
<extension_type>ivr</extension_type>
<extension_type>call_queue</extension_type>
</extension_types>
</parameters>
</request>
You will notice that the extension_types parameter has a sub parameter call extension_type. This denotes that extension_types takes multiple values and extension_types is the parent tag and extension_type is the child tag that will hold the value of each parameter. Mostly, but not always, the parent tag is a plural form of the child tag.
Send Your XML in a Request
After you have your XML file, you can connect to the Extend API and send your file.