Developers

User identification

The users are identified by email addresses. To specify whose availability information you are interested in, use the email address in usual form user@domain.com. The email address must comply with RFC2822.

Availability statuses

There are following availability statuses returned in responses:

Busy User is busy e.g. there is an event that has been marked as busy in any of connected or discovered calendars belonging to the requested user.

Tentative User is tentatively busy e.g. there is an event in any of connected or discovered calendars belonging to the user that has tentatively busy status. Usually this happens when there is an invitation to an event waiting and the user has not answered it yet by either accepting it (then it becomes busy) or declining it (then it becomes free).

When busy and tentative intervals overlay during freebusy calculation e.g. the same time range is in one calendar busy and tentative in other one, busy is reported in the response for overlayed time interval.

Any other time interval that is not reported in a response must be considered to be free – user is available.

API endpoint is: https://isfreebusy.info:444/freebusy

Remind: port is 444.

There are two main pools for processing requests coming to API endpoint – each pool has rate limiting which limits volume of requests that will be processed. The limits vary. Client SSL certificates are used to define to which of two main pool types the request will go:

1. Shared pool – If there is none or Zonio Freebusy default client SSL certificate (see bellow for more details) sent by a client when establishing the connection, the request will go to a shared processing pool. We recommend using this pool for development and testing only.
2. Private pool(s) – If there is a dedicated client SSL certificate sent by a client when establishing the connection, the request will go to a private pool for processing. Contact us to get your certificate and use your own pool. We recommend to do so for any production use.

Default client certificate

Use default client certificate to make sure your implementation works and you have correct system settings and you are ready to use your own dedicated client certificate later. just by replacing the default one. Download default client certificate bundled with Zonio root CA bellow.

Get availability

Retrieves availability for a user/resource in a particular time interval.

Request

GET /{email}?start={start}&end={end}

Parameters

• email :: string Email address of a user/resource
• start :: integer Start of requested time interval as Unix time
• end :: integerEnd of requested time interval as Unix time

Request example

curl -XGET 'https://isfreebusy.info:444/freebusy/zoniocalendar@gmail.com?start=1516470513&end=1517334513'

Response

On success you get JSON document containing an array of availability time objects with following fields:

• start :: string – interval start in iso8601 UTC
• end :: string – interval end in iso8601 UTC
• type :: string – type of time interval – busy or tentative (see ##Availability statuses)

Response example

[
 {
  "end": "2018-01-22T19:00:00Z",
  "start": "2018-01-22T17:00:00Z",
  "type": "busy"
 },
 {
  "end": "2018-01-23T11:00:00Z",
  "start": "2018-01-23T08:00:00Z",
  "type": "tentative"
 }
]

Error codes:

* 404 Free/busy not found – Freebusy not found for requested user e.g. we were not able to find any calendar for that particular email to read freebusy from.
* 429 Too many requests – There were too many requests and the limit of the pool has been reached. You should either display an error message to the user or try sending request again later. If you use your own private request pool, this means you should contact us to upgrade your tier.
* 503 Free/busy not found in time. – Obtaining freebusy from user calendars took too long.