Accessing the API

Protocols

The API uses the XML-RPC protocol as defined in the XML-RPC Specification

All communication with the API are sent over HTTPS (SSL encrypted HTTP).

Location

Every Ubivox customer has their own hostname. From there you can access the XML-RPC API using HTTP POST on /xmlrpc/. An absulute url might look like this:

https://customer.clients.ubivox.com/xmlrpc/

Authentication

The API uses Basic HTTP authentication over an encrypted SSL HTTPS connection.

You create a password to use when authenticating with the API by clicking Account and Users and Security. Click the tab API authentication and click New password.

The new password will be shown to you once so make a note of it. The API authentication tab gives you an overview of all active passwords, when and from where they were last used and an option of deleting each password to remove access to the account.

We do not store your password in plaintext and thus we are not able to tell you your current password.

Throttling

In order for us to guarentee a great quality of service, we enforce a limit on API calls. The limit is based on the current hour of the clock.

When you reach the limit, the system will start replying with the XML-RPC fault code 9997 (Too many calls (throttling)).

Service windows

When Ubivox is not accessible due to service windows or unplanned downtime on the application servers, the system will reply with a 503 SERVICE UNAVAILABLE to your requests.

In very rare occasions, the API load balancer may experience network problems and then you will receive a network timeout.

If either happens, then your request was not processed and you should repeat it at a later time.

All planned service windows will be announced ahead of time in newsletters as well on the status blog (which also contains information on unplanned downtime).

Request log

From your Ubivox web interface you can find a API request log. You will find it from Account then API Requests. This contains a searchable index of all your API requests from the past six months. This is a great tool for debugging your integration with Ubivox.

Debugging

During the development phase of your integration, it might be a help to dump requests and responses as they happen. We provide the option of having the raw requests sent to your e-mail address for your inspection.

If you want to activate this, you will find it in the Ubivox web interface from Account then API. Here you will be able to turn on XML-RPC debugging