Getting started

The quick and easy way to get started.

To get started instantly, click here, find a method and start using it. For more detailed information, please read this page first.

This document describes the various services that Telavox exposes as an open API. These services are primarily intended for 3rd party systems that need to integrate with Home. The reader of this documentation should be familiar with common concepts in Home (the end-user application) and related technologies before attempting to implement a client that utilizes these services.

Changes and additions to our API will be announced on this page. Telavox reserves the right to block usage, in our sole discretion, to our API for anyone who misuses it.

Accessing our API

The Telavox Home API is located at https://api.telavox.se. All API methods' paths are relative to this url.

Authentication and sessions

When a user (web browser or API-client) logs in to Home with her username and password a session cookie is returned that will be required for subsequent requests. A single user can have multiple session active at the same time without restrictions (although most browsers use the same cookie if the user has multiple windows/tabs open accessing Home). All requests to the API that require authentication but are outside an active session will be responded to with a 401 Unauthorized resopnse.

Synchronization

One must keep in mind when designing and adapting systems integrating with Home that any and all data and configuration may be changed from another source. Thus it’s recommended to not store a replica of the data fetched from Home unless it’s very frequently read and it’s accuracy isn’t critical, and when updating information in Home it’s recommended that the information is first refreshed to make sure no modification has been made from another source since the information was first retrieved.

Character encoding and request methods

The content type and encoding of each API method is specified in the Content-Type response header. Most of the responses are JSON formatted, and all are UTF-8 encoded.

The character encoding used in request URLs is not well defined, meaning that non US-ASCII characters might present a problem and not be portable. We highly recommend specifying an appropriate Content-Type header in every request.

Read more

Please see the reference documentation for the details on the API endpoints.

For more information about JSON go to http://www.json.org. Implementations are freely available for most popular languages.

To explore our API in a browser, one can use the excellent Chrome add-on Postman. It can monitor XmlHttpRequests sent by the browser and by analysing these one can get a better understanding of how the API works.