Knowledge Base

Aurinko Calendar API

The Aurinko Calendar API abstracts away differences between popular calendar APIs (Google, Office 365, Outlook.com, MS Exchange) to make it easy to develop calendar integrations.

The Aurinko Calendar API provides a REST interface that focuses on accessing and syncing calendars in a uniform manner.

• Access data for calendars and events, such as event titles, location, description, dates, ...
  
• Full CRUD (create, read, update, delete) capabilities.
  
• Incremental synchronization
  

Aurinko account setup

Start a new sync

A new sync needs to be provisioned by calling the "sync start" method /calendars/{calendarId}/sync. The sync is available per calendar, hence {calendarId} or "primary". timeMin and timeMax specify a time range for the initial full load.

curl -X POST -H 'Authorization: Bearer <account_access_token>' \
    -G https:/api.aurinko.io/v1/calendars/primary/sync \
	-d timeMin=2019-06-03T10:00:00-07:00 \
	-d timeMax=2020-06-03T10:00:00-07:00

The Aurinko platform will initialize all necessary internal resources and let you know when it's ready to serve data. The response should look like this:

{
  "syncUpdatedToken": "asdfghjklpoiuytrew",
  "syncDeletedToken": "zxcvbnmlkjhgfdsaq",
  "ready": true
}

If the response shows ready: false call the "sync start" method again. Once the sync is ready you will get delta tokens syncUpdatedToken, syncDeletedToken and can start loading updated and deleted events. 

Initial full sync

Initial requests /calendars/{calendarId}/sync/updated and /calendars/{calendarId}/sync/deleted are equivalent to a full sync in the specified timeMin,timeMax range, plus loading all updated events (deleted events) since the sync start. 

curl -X GET -H 'Authorization: Bearer <access token>' \
    -G https:/api.aurinko.io/v1/calendars/primary/sync/updated \
    -d deltaToken='{syncUpdatedToken}'

Response:

{
  "nextPageToken": "string",
  "nextDeltaToken": "string",
  "records": [{...}]
}

Continue loading pages using provided 'nextPageToken' until you find another 'nextDeltaToken'.

curl -X GET -H 'Authorization: Bearer <access token>' \
    -G https:/api.aurinko.io/v1/calendars/primary/sync/updated \
    -d pageToken='{nextPageToken}'

Incremental sync

A new deltaToken (nextDeltaToken in a response) is good for loading calendar events that have been modified/deleted since the last sync-updated/sync-deleted request. In cases where a large number of events have changed since the last incremental sync request, you may find a nextPageToken instead of a nextDeltaToken in the response. Continue loading pages using provided nextPageToken until you find another nextDeltaToken.

Other examples

Calendars

To view a list of all calendars a user has access to, make a request to the /calendars endpoint. 

curl -H 'Authorization: Bearer <access token>' \
	-X GET https:/api.aurinko.io/v1/calendars

You can get information for a single calendar by providing the appropriate calendar id, /calendars/{id}. You can use "primary" as an id to get your primary calendar.

curl -H 'Authorization: Bearer <access token>' \
	-X GET https:/api.aurinko.io/v1/calendars/primary

Calendar events

To get a list of events from a calendar, make a request to the /calendars/{id}/events endpoint.

curl -X POST -H 'Authorization: Bearer <access token>' \
	-G https:/api.aurinko.io/v1/calendars/primary/events/range \
	-d timeMin=2019-06-03T10:00:00-07:00 \
	-d timeMax=2020-06-03T10:00:00-07:00

To create a new meeting POST json payload to  /calendars/{id}/events endpoint:

curl -H 'Authorization: Bearer <access token>' \
	-X POST https:/api.aurinko.io/v1/calendars/primary/events \
	-d '{
	"subject": "Business lunch",
	"location": "Our favorite cafe",
	"start": {
	    "dateTime": "2020-02-04T10:00:00Z",
	    "timezone": "America/Los_Angeles"
	},
	"end": {
	    "dateTime": "2020-02-04T11:00:00Z",
	    "timezone": "America/Los_Angeles"
	},
	"meetingInfo": {
	    "attendees": [
	        {
		    "emailAddress": {"address": "partner@example.com"},
		    "type": "required"
		}
	    ]
	}}'

Use PATCH request to update existing events and notify meeting attendees of changes:

curl -X POST -H 'Authorization: Bearer <access token>' \
 	https:/api.aurinko.io/v1/calendars/primary/events/{eventId}?notifyAttendees=true \
	-d '{
	"subject": "Business lunch",
	"location": "Another cool place",
	"start": {
	    "dateTime": "2020-02-05T10:00:00Z",
	    "timezone": "America/Los_Angeles"
	},
	"end": {
	    "dateTime": "2020-02-05T11:00:00Z",
	    "timezone": "America/Los_Angeles"
	},
	"meetingInfo": {
	    "attendees": [
	        {
		    "emailAddress": {"address": "partner@example.com"},
		    "type": "required"
		}
	    ]
	}}'