** DRAFT **
Subject to Change
VirtualCallboard is able to integrate with other applications through its HTTP application programming interface (API).
Generally, you can access the API of any module of VirtualCallboard by adding “api.php” behind any module directory of VirtualCallboard. (For example, adding ‘api.php’ to http://yoursite.vcallboard.com/calls/api.php will return a HTTP response code from the API, while http://yoursite.vcallboard.com/calls/index.php will return a webpage as a response.
How to form your request
The API observes the CRUD (create, read, update, delete) model for APIs. There may be additional ‘read’ type operations available if other supplemental data is useful or needed.
The VirtualCallboard system uses HTTP GET for requesting information from the API and HTTP POST to send information to the API.
For the CREATE, UPDATE, and DELETE operations, the API requires an HTTP POST parameter that is named ‘method’. You can use ‘create’, ‘update’, or ‘delete’ as the value of ‘method’ variable, and this will tell the API what you expect it to do. Specific data that is required along with each method is detailed in the other tabs of this document.
For READ operations, you must submit the apikey GET variable (‘apikey’) and then any other parameter required for the operation you are attempting to achieve. Specific data that is required is detailed in the other tabs of this document.
Response Codes
The VirtualCallboard API will generally respond with a HTTP 200 OK response, even if there is an error. Your application should check the XML response after any CREATE, UPDATE, or DELETE event for an error code. If there is an error, it will be formatted like this:
<?xml version="1.0"?>
<VirtualCallboard>
<error>Friendly error text here</error>
</VirtualCallboard>
Authenticate as System
The application should submit GET or POST variable ’apikey’ with the associated key generated by your VirtualCallboard. To get an API key for your VirtualCallboard, visit the Site Administration page.
Authenticate as User
A users credentials should be submitted by POST or GET using the following variables:
username
password
The username should be the user’s VirtualCallboard username in plain text. Any ASCII character is allowed.
The password should be a MD5 hash of the user’s password. The password should be hashed before being sent to the API.
http://yoursite.vcallboard.com/calls/api.php
Supported Operations
| Name | Required/Optional | Expected Value |
|---|---|---|
| method | required | value must be ‘create’ |
| company_id | optional defaults to ’0′ (All Companies) if not set |
integer (see Get Company method) |
| title | required | string (255 character max) |
| tdstart | required | Date value: YYYY-MM-DD HH:MM:SS |
| tdend | required | Date value: YYYY-MM-DD HH:MM:SS |
| type | required | integer (see Get Call Type method) |
| location_id | optional NULL value indicates that ‘location’ value takes precedence |
integer (see Get Call Location method) |
| location | optional | string (255 character max) |
| notes | optional | string (255 character max) |
| active | required | integer: 0 = draft, 2 = active |
| openclose | required | integer: 0 = closed call, greater than 0 create an open call and is the number of open slots for the call. |