# Calendar API

## Aurinko Calendar API

***

The Aurinko Calendar API is part of the Aurinko Unified API platform, enabling developers to integrate calendar functionalities effortlessly into their applications. This API abstracts the differences between calendar management services such as Google, Outlook, iCloud Calendar, offering a consistent interface for calendar-related operations.

### Functionality

***

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

* 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

***

First, create your account in the [Aurinko portal](https://app.aurinko.io/), then follow the guide to [get your developer API keys](https://docs.aurinko.io/getting-started/get-your-developer-api-keys).

### Calendar API Endpoints

***

#### Calendars

Each account connected to Aurinko can have zero or more [calendars](https://apirefs.aurinko.io/#tag/Calendars), and each calendar contains a collection of individual events. Accounts can have many calendars including a primary calendar, secondary calendars, read access calendars, and shared team calendars.

#### Events

[Events](https://apirefs.aurinko.io/#tag/Events) are objects within a calendar that generally support all features and attributes of modern scheduling apps like event names, list of participants, descriptions, location, time, etc. Aurinko supports key event functionality, including sending email invites, response status checks and notifications, creating and modifying events, and recurring events.

#### Synchronization

[Calendar sync](https://apirefs.aurinko.io/#tag/CalSync) methods allow developers to implement incremental synchronization of calendar data in a uniform manner across different calendar providers. Aurinko supports requesting updated as well as deleted calendar events, reporting series master and exceptions, auto-expanding a sync range.

#### Free/busy schedule

[Free/busy schedule](https://apirefs.aurinko.io/#tag/FreeBusySchedule) methods allow developers to check free/busy status for a calendar or available time slots for a meeting.

#### **Booking profiles**

[Booking profiles](https://apirefs.aurinko.io/#tag/Booking) methods allow developers to build calendar availability and meeting scheduling apps. List, create, update, and delete booking profiles associated with a user calendar. See meeting time availability according to a booking profile configuration.

### Calendar sync quickstart

***

**Start a new sync**

A new sync needs to be provisioned by calling the *sync-start* method <mark style="color:red;">`/calendars/{calendarId}/sync`</mark> The sync is available per calendar, hence {calendarId} or *primary*. <mark style="color:red;">`timeMin`</mark> and <mark style="color:red;">`timeMax`</mark> specify a time range for the initial full load.

```bash
curl -X POST -H 'Authorization: Bearer <account_access_token>'
    -G https:/api.aurinko.io/v1/calendars/primary/sync[?awaitReady=false]
        -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:

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

If the response shows <mark style="color:red;">`ready: false`</mark> call the *sync-start* method again. Once the sync is ready you will get delta tokens <mark style="color:red;">`syncUpdatedToken`</mark>, <mark style="color:red;">`syncDeletedToken`</mark> and can start loading updated and deleted events.

#### Initial full sync

Initial requests <mark style="color:red;">`/calendars/{calendarId}/sync/updated`</mark> and <mark style="color:red;">`/calendars/{calendarId}/sync/deleted`</mark> are equivalent to a full sync in the specified <mark style="color:red;">`timeMin`</mark>, <mark style="color:red;">`timeMax`</mark> range, plus loading all updated events (deleted events) since the sync start.

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

*Response:*

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

Continue loading pages using provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

```bash
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 response) is provided 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 <mark style="color:red;">`nextPageToken`</mark> instead of the <mark style="color:red;">`nextDeltaToken`</mark> in the response. Continue loading pages using the provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

### Other examples

***

#### Calendars

To view a list of all calendars a user has access to, make a request to the <mark style="color:red;">`/calendars`</mark> endpoint.

```bash
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, <mark style="color:red;">`/calendars/{id}`</mark>. You can use *primary* as an ID to get your primary calendar.

```bash
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 <mark style="color:red;">`/calendars/{id}/events`</mark> endpoint.

```bash
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 <mark style="color:red;">`/calendars/{id}/events`</mark> endpoint:

```bash
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:

```bash
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"
            }
        ]
    }
}'
```

#### Query parameters

<table><thead><tr><th width="156.5078125">Name</th><th width="95.5703125">Type</th><th width="101.9296875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>notifyAttendees</code></td><td><code>boolean</code></td><td><code>true</code></td><td><p>Indicates whether to send event invitations or updates to attendees. Set to <code>false</code> to create or update an event silently, without sending notifications.</p><p><strong>Supported by:</strong> Google, Clio.</p></td></tr><tr><td><code>bodyType</code></td><td><code>string</code></td><td>—</td><td><p>Defines the format of the event description. Possible values:</p><p>- <code>html</code> — event description is formatted as HTML.</p><p>- <code>text</code> — event description is plain text.</p></td></tr><tr><td><code>returnRecord</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Determines whether the response should include the full event record after creation. If <code>false</code>, the API will return only the event ID. Setting this to <code>true</code> may result in an additional request to the provider API to fetch the full record.</td></tr></tbody></table>