Kloudless API Guide

# Kloudless API interaction

  • Connector Category: Calendar
  • Unified APIs Supported: Calendar, Activity, Team

# Google Calendar quickstart

A useful feature that the Google Calendar connector and Activity Monitoring can provide is the ability to sync calendar events by monitoring for changes in a connected user’s calendar. This quickstart guide will describe how to implement calendar sync by monitoring for calendar changes using the Activity API.

Implementing calendar sync requires you to do a few steps:

  1. Enable activity monitoring by creating a subscription.
  2. Connect your account.
  3. Retrieve initial calendar data.
  4. Monitor for new calendar activity.
  5. Retrieve new activity data by querying the Activity API.

# Enable activity monitoring

Subscriptions are required to use Activity Monitoring endpoints. To enable a default subscription to be created for each account you connect, go to the Activity Monitoring Configuration page in your Kloudless Developer Portal and check the box labelled Track Activity. Accounts connected before enabling Track Activity will need to be reconnected for a subscription to be created for that account.

The alternative option is to create a subscription for the account using the create a subscription endpoint. This method also allows you to specify a specific calendar to be monitored by the subscription by passing the calendar ID(s) in the monitored_resources attribute at the time of creation.

# Connect your account

Go to the API Explorer and click Connect A New Account. Select Google Calendar and allow access to the requested scopes. If you did not enable Track Activity, create a subscription manually.

We can verify that a default subscription was created for the account by making a GET request to the list subscriptions endpoint: /v1/accounts/{account_id}/subscriptions/

In the following example response, we see that a subscription indeed exists:

{
  "total": 1,
  "count": 1,
  "objects": [
    {
      "id": <id>,
      "account": <account>,
      "type": "subscription",
      "api": "activity",
      "active": true,
      "disable_reason": "",
      "subscription_type": "changes",
      "default": false,
      "expiry": "2020-10-28T08:31:43.587905Z",
      "created": "2020-10-27T08:18:34.053393Z",
      "modified": "2020-10-27T08:31:58.742193Z",
      "monitored_resources": [
        "root"
      ],
      "monitored_resource_object_type": "calendar",
      "monitored_resource_api": "calendar",
      "last_cursor_updated_at": "2020-10-27T08:31:58.394494Z",
      "last_cursor": "2334",
    }
  ],
  "type": "object_list",
  "api": "activity"
}

# Authenticating your app's users

See the Authentication API docs for details on how to authenticate your users.

# Retrieve initial calendar data

Once an account is connected, make a request to the list calendar events endpoint to retrieve existing events from the account's primary calendar. This is useful for initializing your app with a user's calendar data the first time they connect to your app.

# Monitoring for activity

# Polling

Polling is the simplest way of monitoring for activity, and requires sending requests to the list activity endpoint at regular intervals to check for updates.

For the simplicity of this guide, we will mimic the polling method by manually querying the list activity endpoint for new activity using the API Explorer.

We recommend using webhooks in your application. Configuring webhooks allows your app to receive real time notifications when changes occur in the resource you are subscribed to. Once a notification is received via webhook, your application should make a request to the list activity endpoint to retrieve activity information.

Configure a webhook URI to receive activity notifications in the Webhooks section of the Activity Monitoring Configuration page in your Kloudless Developer Portal.

For details on each method of monitoring for activity, see the Activity Monitoring usage guide.

# Retrieving new activity

Retrieve new activity by making a GET request to the list activity endpoint: /v1/accounts/{account_id}/subscriptions/{subscription_id}/activity/

If your calendar has not had any new changes since creating the subscription, you will get the following response:



 





{
  "objects": [],
  "count": 0,
  "cursor": 0,
  "api": "events",
  "type": "object_list"
}

objects is an empty list and count is 0, indicating that there are no activity objects to return.

Next, add an event to your connected account’s calendar. After creating the calendar event, query the list activity endpoint again. The response will contain an activity object with the newly created event's metadata in the objects list:







 













































 
 




{
  "objects": [ 
    {
      "id": "<object_id>",
      "account": "<account_id>",
      "subscription": "<subscription_id>",
      "action": "+", # An event was created
      "ip": null,
      "modified": "2020-11-02T04:33:41.031000Z",
      "type": "add",
      "user_id": null,
      "api": "activity",
      "metadata": {
        "api": "calendar",
        "type": "event",
        "id": "<event_id>",
        "account_id": "<account_id>",
        "calendar_id": "<calendar_id>",
        "ical_uid": "<ical_uid>",
        "recurrence_type": "solo",
        "creator": {
          "id": null,
          "name": null,
          "email": "<my_email>@gmail.com"
        },
        "organizer": {
          "id": null,
          "name": null,
          "email": "<my_email>@gmail.com"
        },
        "on_organizer_calendar": true,
        "attendees": [],
        "created": "2020-11-02T04:33:41Z",
        "modified": "2020-11-02T04:33:41.031000Z",
        "all_day": false,
        "start": "2020-11-02T08:00:00-08:00",
        "start_time_zone": "America/Los_Angeles",
        "end": "2020-11-02T09:00:00-08:00",
        "end_time_zone": "America/Los_Angeles",
        "name": "Example Event Name",
        "description": null,
        "location": "Berkeley, CA, USA",
        "status": "confirmed",
        "visibility": null,
        "attachments": [],
        "use_default_reminder": true,
        "reminders": [],
        "reminder": null,
        "href": "https://api.kloudless.com/v1/accounts/<account_id>/cal/calendars/<calendar_id>/events/<event_id>"
      }
    }
  ],
  "count": 1, # One Activity object was returned
  "cursor": "3489579434", # New cursor value
  "api": "events",
  "type": "object_list"
}

Note that cursor has been updated. Save the latest value of cursor each time you receive a response and pass it into subsequent requests to /activity to avoid seeing the same activity data in future responses.

In this example, demonstrated in the API Explorer, setting cursor to 3489579434 will return new activity which has occurred after the previous response.

Pass in the latest value of cursor when querying the Activity API

Pass in the latest value of cursor when querying the Activity API.

The objects attribute of the response is a list of activity objects, each containing data for new activity. With this data, your application will have the necessary information about new or updated calendar events to sync changes from the account’s Google Calendar.

# Support

Please contact us at support@kloudless.com with any questions you may have. We'd be happy to help you get set up.

← Hubspot →