Setup

Authentication

Authentication to the API is done by unique keys linked to a Callcap login.
Keys can be generated, and revoked, from My Profile on the Callcap App.
- Access for a given key is controlled by the access the generating account has.
- Keys may be revoked by the user at any time
Each request to the API must include an HTTP "Authorization" header with value "Bearer your_api_key" where your_api_key is an API key generated from the My Profile page.

Example:

If your API key is abcdefghijklmnopqrstuvwxyz, your headers may look like this.

GET /v2/get/calls/ HTTP/1.1  
Host: api.callcap.com  
Authorization: Bearer abcdefghijklmnopqrstuvwxyz

Response Format

The Callcap API will return results from GET requests in either JSON or XML.
To specify return format use the HTTP header "accept" set to the mimetype of the format you would like.
JSON is the default. To explicitly specify it, you would set the header as Accept: application/json.
To get results in XML, you would set the header to Accept: application/xml.
If the request is successful, the HTTP status of 200 OK will be returned with the response as well as a status attribute set to "success". If the response is JSON, status will be a top level attribute. If the response is XML, status will be an attribute on the top level node.
POST responses and error messages are always returned in JSON.

Example:

If your API key is abcdefghijklmnopqrstuvwxyz and you would like results in XML format, your headers may look like this.

GET /v2/get/calls/ HTTP/1.1
Host: api.callcap.com
Authorization: Bearer abcdefghijklmnopqrstuvwxyz
Accept: application/xml

Error Responses

Error	Header	Example Response
Authentication key was not sent or is not an active/valid key.	HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="https://api.callcap.com/v2/"	{"status":"unauthorized", "message":"Your key is invalid"}
The requested resource did not exist or did not have anything to say.	HTTP/1.1 404 Not Found	{"status":"fail", "message":"API endpoint does not exist"}
Required parameters were not sent or the request was otherwise incorrect.	HTTP/1.1 400 Bad Request	{"status":"invalid", "message":"Invalid request"}
Something broke on our end and Callcap development has been notified.	HTTP/1.1 500 Internal Server Error	{"status":"error", "message":"An error has occurred and development has been notified"}