VoIP Spear API

The VoIP Spear API gives you the ability to build mashups and add-ons to VoIP Spear, or integrate VoIP Spear in your own application. Our API is implemented as plain XML over HTTP. The API is RESTful, and it supports 4 HTTP verbs -- GET, POST, PUT, and DELETE.

Please note the following:

• the "Content-Type" header in your requests must be "application/xml"
• the "Accept" header needs to be "application/xml"
• the expected response for all requests is "200 OK" (with the exception of POST/create requests in which case the expected response is "201 Created")

Check your plan to see if you can access the API. Note that our free plans do not allow API access.

Note that only your Master account is allowed to access the API. Your Master account is the account you signed up with initially.

We recommend you use curl to test the API. Try the following command when you first start.

curl -H 'Accept: text/xml' -i -X GET http://voipspear.com

HTTP/1.1 200 OK
Connection: close
Date: Tue, 20 Jan 2009 04:32:34 GMT
Status: 200 OK
Server: Mongrel 1.1.4
Content-Type: application/xml; charset=utf-8
Content-Length: 153

VoIP Spear (v1.1.0) API
Property of Toepoke Software, Inc.  
All rights reserved.

For more information, refer to www.voipspear.com and www.toepoke.com.

The root URL (http://voipspear.com) responds to all requests with a generic message listing VoIP Spear's version number and a basic copyright message.

Take a look at the next example*. It shows you how to query the API for a list of your user accounts. If this API request fails with a "404 Not Found" response, you do not have access to the API (most likely because the plan you are subscribed to does not allow API access). If this request succeeds, then you have API access.

* For all you REST geeks outs there -- yes, we're aware that GET http://www.voipspear.com/users isn't really RESTful. However, we wanted to implement this one hack because it makes it easier to get started using the API.

curl -u {username}:{password} -H 'Accept: text/xml' \
  -i -X GET http://voipspear.com/users

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <category>Admin</category>
    <created-at type="datetime">2008-01-14T04:29:22Z</created-at>
    <deleted-at type="datetime" nil="true"></deleted-at>
    <email>support@toepoke.com</email>
    <id type="integer">1</id>
    <name>Account Name</name>
    <time-zone>Eastern Time (US & Canada)</time-zone>
    <username>username</username>
  </user>
</users>