The Kaisa API allows master account holders/partners and customers to access and alter data in the Kaisa platform via a REST-ful web service. This API is based on REST principles but might differ from the “unofficial standard” as described on Wikipedia. All valid resources and methods are described on this site.

Base URL

The base URL for a request is handed out to the account holder together with the account holders security details. The base URL will look like:

https://<URL>/

Version

Due to backwards compatibility, different versions of this API will coexist on this web service. Because of this the requested API version should be added to the base URL. The current version is handed out to the partner together with the partners security details. To access the latest version of the API, found here, the URL should be:

https://<URL>/<version>/

Consuming

To consume methods “POST” or “PUT” in any resource, parameters shall be sent as urlencoded key/value pairs. For methods “GET” and “DELETE”, URL query string parameters are used. To receive data for one specific customer, the partner should request the resource “customers” with method “GET” and specify the ID of the customer. The request should be:

GET /customers/1

To receive a list of all customers, the partner could instead request:

GET /customers

Some methods exists as sub-resources and there are two ways to consume a sub-resource, both these examples are valid:

GET /customers/1/voicemail_greetings/2

GET /customers/voicemail_greetings?customer_id=1&vm_greeting_id=2

To create a new customer, the partner should request the resource “customers” with method “POST”. The request could be:

POST /customers
name=Freespee+AB&custnr=123

To update data on a specific customer, the partner should request the resource “customers” with method “PUT”, specify the id of the customer and the data to be updated. The request could be:

PUT /customers/1
name=Freespee+New+AB

Normally with REST, the “PUT” method is used both to update and create. However in this implementation, method “PUT” can only be used to update data. To create anything in a resource method “POST” must be used.

Custom fields

The data model of this API include something called “custom fields”. Custom fields are dynamic fields defined by the partner and Kaisa at delivery. Therefore the definition of the custom fields cannot be changed directly. The custom fields can be defined for “customers” and “sources” independently. The value of defined custom fields can be changed directly by the partner.

Security

This API support only HTTPS connections. To access this API account holders must support HTTP digest authentication. Kaisa will send authentication details to the account holder. The account holder must take precautions to prevent these details from being exposed to the public. On top of digest authentication, Kaisa must also know the IP address(es) of the account holders servers. The account holder must send Kaisa a list of IP address(es) that should have access to this API, so they can be added to a whitelist (contact support@kaisa.io for IP whitelisting). 

URL parameters

For the methods “GET” and “DELETE”, URL parameters may be passed at the end of the URL. All parameters must be specified using GET query string. For example:

GET /statistics/cdrs?customer_id=1

Request data

Request data is usually sent as form urlencoded key/value pairs. The HTTP Content-Type header should normally be set to application/x-www-form-urlencode. For example:

Content-Type: application/x-www-form-urlencode
POST /customers
name=Freespee+AB&custnr=abc123

Some methods support JSON POST data in which case the Content-Type should be set to application/json.

Charset and encoding

The UTF-8 charset shall be used at all times. All data in responses will be in UTF-8 charset. All URL parameters must be URL-encoded.

Request headers

This API relies on the HTTP "Host"-header to be sent as per the HTTP/1.1 specification. If you are using the older HTTP/1.0 please upgrade your client or manually set the "Host"-header in your requests. 

Response data

Response data can be returned as different formats (as described later in this document), depending on what format the partner prefers. A simplified response from the customer's resource in JSON format could look like:

{
 "customers":[{
  "customer_id":"1",
  "name":"Freespee AB",
  "custnr":"123",
  "corporateid":"123",
  "email":"",
  "custom_1":"abc",
  "custom_2":null
 }]
}

And the same response data in XML format would look like:

<?xml version="1.0" encoding="UTF-8"?>
<customers>
 <customer>
  <customer_id>1</customer_id>
  <name>Freespee AB</name>
  <custnr>123</custnr>
  <corporateid>123</corporateid>
  <email></email>
  <custom_1>abc</custom_1>
  <custom_2/>
 </customer>
</customers>

Response types

Response type can be either JSON or XML. The default response type is always JSON. To change or force a different response type, add .json or .xml to the resource in the URL. For example:

GET /customers.xml/1

The HTTP Accept-header can also be used together with application/json or application/xml, for example:

Accept: application/xml
GET /customers/1

Response codes

HTTP status codes are used to return appropriate statuses for each request.

• 200 OK: The request was successfully handled.
• 400 Bad Request: The request was invalid. In most cases, an explanation will be displayed to pinpoint the problem.
• 401 Unauthorized: Authentication credentials are missing or incorrect. If credentials are correct, the partners IP-address might have changed.
• 403 Forbidden: The request was handled, but has been refused. In most cases, an explanation will be displayed.
• 404 Not Found: The requested resource was not found.
• 405 Method Not Allowed: The requested method is not allowed.
• 500 Internal Server Error: The API is not responding, please contact Kaisa's support.
• 501 Not Implemented: The specific method is not yet implemented.
• 503 Service Unavailable: Service is up, but unresponsive. Please try again later.

Timestamps

All timestamps returned are presented in UTC timezone.

Paging

Some resources in this API implements paging. When paging occurs, the result is returned partial using the following properties.

An example output from /statistics/cdrs:

{
 "total":10,
 "page":0,
 "pagesize":1000,
 "numpages":1,
 "cdrs":[{
  ...
 }]
}

Example request:

GET /statistics/cdrs&page=2

Tips and tricks

If the account holders system do not support methods PUT or DELETE, these methods can be set via the URL query string to override HTTP method. The format is _method=<method>. For example:

POST /customers/1?_method=PUT
name=Freespee+New+AB

The HTTP-header X-HTTP-Method-Override is also allowed. For example:

X-HTTP-Method-Override: PUT

Test using cURL

An easy way to test the API is to use cURL. Here follows some examples that could be used to test access to the API.

Ping API:

curl --digest -u 'user':'pass' 'https://<URL>/<version>/miscellaneous/ping'

Retrieve all customers:

curl --digest -u 'user':'pass' 'https://<URL>/<version>/customers'

Retrieve a specific customer:

curl --digest -u 'user':'pass' 'https://<URL>/<version>/customers/1'

Adding a new customer:

curl --digest -u 'user':'pass' -X POST -d 'name=Freespee+AB&custnr=abc123' 'https://<URL>/<version>/customers'

Kaisa API Getting started