Introduction to the Calendar API 

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can perform API requests to the Calendar API endpoints listed below.

Here are the supported services, listed with service identifiers:

  • Calendar Services
    • Google Calendar: google_calendar
    • Outlook Calendar, or Exchange Online: outlook_calendar
    • CalDAV: caldav
    • Exchange Server: exchange

The Calendar API supports two endpoints to retrieve calendar and event resources.

  • Calendar

  • Event

Each set of endpoints is represented below with a description of the resource being represented. Fields that contain nested object representations are noted.

In addition, the entire original object can be obtained by requesting raw data when performing the API request. This raw data will be present in the raw attribute in the response received.

Similarly, raw data can be sent upstream to services while creating and updating objects as well using the same format. Include the upstream object attribute names and values in the raw -> object field in the request body.

Here are services which support raw -> object field when creating and updating calendars/events:

The Calendar API has the following available object types:

  • calendar

  • event

  • availability


Calendars 

A Calendar object represents metadata on a calendar that belongs to the user. A calendar has the following attributes:

  • id Unique identifier for the calendar. primary can be used as an alias for the id of the user’s primary calendar.

  • name Name of the calendar

  • description Additional details about the calendar

  • location Geographic location of the calendar as free-form text

  • timezone The time zone of the calendar (IANA Time Zone Database name. Not supported in outlook_calendar)

  • raw Underlying object retrieved from the service.

  • type Will always be calendar

  • api Will always be calendar

List Calendars 

list calendarsGET /accounts/{account_id}/cal/calendars{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of calendar objects

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 3,
      "next_page": null,
      "objects": [
        {
          "description": null,
          "name": "kloudless@gmail.com",
          "location": null,
          "timezone": "America/Los_Angeles",
          "id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
          "account_id": "123",
          "type": "calendar",
          "api": "calendar"
        },
        {
          "description": null,
          "name": "Contacts",
          "location": null,
          "timezone": "America/Los_Angeles",
          "id": "fI2NvbnRhY3RzQGdyb3VwLnYuY2FsZW5kYXIuZ29vZ2xlLmNvbQ==",
          "account_id": "123",
          "type": "calendar",
          "api": "calendar"
        },
        {
          "description": null,
          "name": "Holidays in United States",
          "location": null,
          "timezone": "America/Los_Angeles",
          "id": "fZW4udXNhI2hvbGlkYXlAZ3JvdXAudi5jYWxlbmRhci5nb29nbGUuY29t",
          "account_id": "123",
          "type": "calendar",
          "api": "calendar"
        }
      ],
      "page": "1",
      "type": "object_list",
      "api": "calendar"
    }

Create a Calendar 

create a calendarPOST /accounts/{account_id}/cal/calendars

To create an calendar, perform a POST request with a JSON object of the following parameters:

  • name: Name of the calendar

  • description: Description of the calendar

  • location: Geographic location of the calendar

  • timezone: Timezone of the calendar (not supported in outlook_calendar)

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars' \
    -XPOST -d '{
        "name": "My Calendar",
        "description": "A calendar for events",
        "location": "San Francisco, CA",
        "timezone": "US/Pacific",
        "raw": {
            "object": {
                "Color": 1
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "name": "My Calendar",
      "description": "A calendar for events",
      "location": "San Francisco, CA",
      "timezone": "US/Pacific"
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "description": "A calendar for events",
      "name": "My Calendar",
      "location": "San Francisco, CA",
      "timezone": "America/Los_Angeles",
      "id": "fRTEroiaERgiwjefwreGfwe",
      "account_id": "123",
      "type": "calendar",
      "api": "calendar"
    }

Retrieve a Calendar 

retrieve a calendarGET /accounts/{account_id}/cal/calendars/{calendar_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "description": "A calendar for events",
      "name": "My Calendar",
      "location": "San Francisco, CA",
      "timezone": "America/Los_Angeles",
      "id": "fRTEroiaERgiwjefwreGfwe",
      "account_id": "123",
      "type": "calendar",
      "api": "calendar"
    }

Update a Calendar 

update a calendarPATCH /accounts/{account_id}/cal/calendars/{calendar_id}

To update a calendar, create a JSON object with any of the following properties:

  • name

  • description

  • location

  • timezone (not supported in outlook_calendar)

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "name": "My Calendar",
        "description": "A calendar for my events"
    }' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "name": "My Calendar",
      "description": "A calendar for my events"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "description": "A calendar for events",
      "name": "My Calendar",
      "location": "San Francisco, CA",
      "timezone": "America/Los_Angeles",
      "id": "fRTEroiaERgiwjefwreGfwe",
      "account_id": "123",
      "type": "calendar",
      "api": "calendar"
    }

Delete a Calendar 

delete a calendarDELETE /accounts/{account_id}/cal/calendars/{calendar_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/accounts/me/cal/calendars/456
  • Response  204

Events 

An Event object represents metadata of an entry on a particular calendar with information including the title, start and end times, attendees, and frequency.

An email notification will be sent to all attendees when an event is created, updated, or deleted. However, if only attendees is being updated, then only the ones being added or deleted will receive the notification. Supported in outlook_calendar and google_calendar.

Note: Google Calendar allows users to customize notifications for each individual calendar. If a user is not receiving notification emails, please refer the user to their calendar settings. The settings can be found at: Google Calendar -> Settings -> Expand the default calendar under Settings for my calendars section -> General notifications -> set Email to the event types you want to enable notification.

An event has the following attributes:

  • id Unique identifier for the event

  • calendar_id Unique identifier for the calendar which this event belongs to. primary can be used as an alias for the calendar_id of the user’s primary calendar.

  • name Name of the event

  • description Additional details about the event

  • created ISO 8601 timestamp indicating when the event was created

  • modified ISO 8601 timestamp indicating when the event was last modified

  • start ISO 8601 timestamp indicating when the event starts

  • end ISO 8601 timestamp indicating when the event ends

  • organizer A Person object describing the organizer

  • creator A Person object describing the creator (only supported in google_calendar)

  • attendees A list of Person objects describing each attendee

  • location Geographic location of the calendar as free-form text

  • attachments A list of File objects attached to the event

  • reminder (deprecated) Object with details about the event’s reminders for this user account. This will be removed in v2. Please use reminders instead.

  • use_default_reminder true to use the calendar’s default reminder; false otherwise. Only supported for google_calendar; absent otherwise. Defaults to true. If true, reminders is ignored.

  • reminders A list of Reminder objects that each contain information on reminders about the event to the user. See notes below on the structure of each Reminder object. The maximum number of reminder objects depend on the service:

    • google_calendar: up to 5
    • outlook_calendar, exchange: only 1
    • caldav: no limit inherently specified in the protocol although server implementations may vary.
  • recurrence A list of recurrence objects that contain information about a recurring event.

  • recurrence_type

    • solo: A stand-alone event.
    • recurring: A recurring event.
    • recurring_master: The primary/master event in the series of recurring events.
  • recurring_master_id The unique identifier for the primary/master event in the series of recurring events. Will be unavailable if the event is not a recurring event or if the event is already the primary/master event in the series.

  • custom_properties A list of custom property objects. Custom properties (some services may call them extended properties) are key-value pairs that allow the user or application to add extra information to calendar events.

    The following services are currently supported:

    • google_calendar
  • visibility Visibility of the event

    • default: Default visibility of the calendar
    • public: The event is public and event details are visible to all readers of the calendar
    • private: The event is private and only event attendees may view event details
    • confidential: The event is private.
  • transparent A boolean value indicating if this event blocks time on the calendar.

    • true: The event does not block time on the calendar and the time is still available.
    • false: The event does block time on the calendar and the time is not available.
  • status State of the event {confirmed, cancelled}

  • raw Underlying object retrieved from the service

  • type Will always be event

  • api Will always be calendar

Reminder objects have the following structure:

  • minutes Number of minutes before the start of the event that the reminder should trigger at.

  • method The method used to remind the user about this event. Defaults to popup. The possible values depend on the services:

    • google_calendar: email, popup
    • outlook_calendar, exchange: popup
    • caldav: email, popup, audio
  • popup The description present in the pop-up. Only supported for caldav. Required for caldav if the method is popup.

  • email Email object. Only supported for caldav. Required for caldav if the method is email. Email Reminder objects have the following structure:

    • summary The subject text of the email.
    • description The body text of the email.
    • to A list of recipients’ email addresses.

Person objects have the following structure:

  • id profile ID of the person.

  • name Name of the person. null if unavailable.

  • email Email address of the person.

  • status Status of the person’s response to the meeting invitation. One of accepted, declined, tentative, or pending. null if unavailable.

  • required Read-only. A boolean indicating whether this is a required attendee.

  • resource Read-only. A boolean indicating whether the attendee is a resource.

File objects have this structure:

  • id ID of the file

  • name Name of the file

  • url URL to download the file from

  • mime_type Content type of the file

Custom property objects have the following structure:

  • key A unique string to indicate a key/ID for this custom property.

  • value A string to store data.

  • private Optional. The default is true. This is for Google Calendar to indicate whether this property will be stored in private or shared. This field is required if you patch a Google Calendar event with custom properties.

    For more info, please refer to Google Calendar Event extendedProperties

List Events 

list eventsGET /accounts/{account_id}/cal/calendars/{calendar_id}/events{?start,end,page}

The response contains the following information:

  • count Number of events on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of event objects

For Google Calendar:

  • recurrence will be unavailable when listing events.

  • custom_properties and custom_properties.private will be included in the response.

  • Parameters
  • start
    string (optional) 

    ISO 8601 timestamp indicating the start of the range of events to retrieve, by event start time. The default value is the start of Unix Epoch Time (1970-01-01T00:00:00Z).

    end
    string (optional) 

    ISO 8601 timestamp indicating the end of the range of events to retrieve, by event end time. Required by Outlook Calendar. The default is to retrieve all events into the future.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "end": "2016-11-01T02:00:00Z",
          "description": "testing event",
          "created": "2016-11-01T06:24:38Z",
          "creator": {
            "email": "kloudless@gmail.com",
            "id": null,
            "name": "kloudless inc"
          },
          "attachments": [
            {
              "url": "https://drive.google.com/file/d/0B4IICHrATMnUeF9YWlhRZ0N1ZG8/view?usp=drive_web",
              "id": "0B4IICHrATMnUeF9YWlhRZ0N1ZG8",
              "mime_type": "image/jpeg",
              "name": "kloudless-logo.png"
            }
          ],
          "modified": "2016-11-01T07:39:09.420000Z",
          "visibility": null,
          "name": "Test Event",
          "recurrence": [],
          "recurrence_type": "solo",
          "custom_properties": [
            {
              "key": "color",
              "value": "green",
              "private": true
            }
          ],
          "raw": {
            "object": {
              "status": "confirmed",
              "updated": "2016-11-01T07:39:09.420Z",
              "description": "testing event",
              "sequence": 0,
              "iCalUID": "u2ioohjbrgcf5eiqppe495mapo@google.com",
              "organizer": {
                "self": true,
                "displayName": "kloudless inc",
                "email": "kloudless@gmail.com"
              },
              "id": "u2ioohjbrgcf5eiqppe495mapo",
              "attachments": [
                {
                  "mimeType": "image/jpeg",
                  "fileUrl": "https://drive.google.com/file/d/0B4IICHrATMnUeF9YWlhRZ0N1ZG8/view?usp=drive_web",
                  "iconLink": "https://ssl.gstatic.com/docs/doclist/images/icon_11_image_list.png",
                  "fileId": "0B4IICHrATMnUeF9YWlhRZ0N1ZG8",
                  "title": "kloudless-logo.png"
                }
              ],
              "kind": "calendar#event",
              "end": {
                "dateTime": "2016-11-01T18:00:00-08:00"
              },
              "created": "2016-11-01T06:24:38.000Z",
              "htmlLink": "https://www.google.com/calendar/event?eid=dTJpb29oamJyZ2NmNWVpcXBwZTQ5NW1hcG8ga2xvdWRsZXNzLnRlc3QudGltb3RoeUBt",
              "reminders": {
                "useDefault": false,
                "overrides": []
              },
              "summary": "Test Event",
              "start": {
                "dateTime": "2016-11-01T17:00:00-08:00"
              },
              "etag": "\"2959600698840000\"",
              "location": "PIER 39, Beach Street & The Embarcadero, San Francisco, CA 94133, USA",
              "creator": {
                "self": true,
                "displayName": "kloudless inc",
                "email": "kloudless@gmail.com"
              }
            },
            "type": "event"
          },
          "attendees": [],
          "location": "PIER 39, Beach Street & The Embarcadero, San Francisco, CA 94133, USA",
          "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
          "use_default_reminder": false,
          "reminders": [],
          "start": "2016-11-01T01:00:00Z",
          "id": "fdTJpb29oamJyZ2NmNWVpcXBwZTQ5NW1hcG8=",
          "organizer": {
            "email": "kloudless@gmail.com",
            "id": null,
            "name": "kloudless inc"
          },
          "account_id": "123",
          "type": "event",
          "api": "calendar"
        }
      ],
      "type": "object_list",
      "api": "calendar"
    }

Create an Event 

create an eventPOST /accounts/{account_id}/cal/calendars/{calendar_id}/events

To create an account, perform a POST request with a JSON object of the following parameters:

  • name: Name of the event (required)

  • description: Description of the event

  • start: ISO 8601 timestamp indicating when the event starts (required)

  • end: ISO 8601 timestamp indicating when the event starts (required)

  • organizer: A Person object describing the organizer

  • creator: A Person object describing the creator (only supported in google_calendar)

  • attendees: A list of Person objects describing each attendee

  • location: Geographic location of the event

  • attachments: A list of File objects to attach to the event

  • use_default_reminder: Indicates whether to use the default reminder (only supported for google_calendar; ignored otherwise)

  • reminders: A list of reminder objects about the event’s reminders for the user account

  • recurrence: A list of recurrence objects that contain information about a recurring event

  • custom_properties: A list of custom property objects.

  • visibility: Visibility of the event

  • transparent: A boolean value of transparency of the event

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events' \
    -XPOST -d '{
        "name": "Event",
        "start": "2016-10-01T12:30:00Z",
        "end": "2016-10-01T13:30:00Z",
        "creator": {
            "name": "Company Owner",
            "email": "owner@company.com"
        },
        "raw": {
            "object": {
                "Importance": "Low"
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "name": "Event",
      "start": "2016-10-01T12:30:00Z",
      "end": "2016-10-01T13:30:00Z",
      "creator": {
        "name": "Company Owner",
        "email": "owner@company.com"
      },
      "custom_properties": [
        {
          "key": "color",
          "value": "green"
        }
      ]
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "end": "2016-10-01T13:30:00Z",
      "description": null,
      "created": "2016-10-01T06:24:38Z",
      "creator": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "attachments": [],
      "modified": "2016-10-01T07:39:09.420000Z",
      "visibility": null,
      "name": "Event",
      "recurrence": [],
      "recurrence_type": "solo",
      "custom_properties": [
        {
          "key": "color",
          "value": "green",
          "private": true
        }
      ],
      "attendees": [],
      "location": null,
      "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
      "use_default_reminder": true,
      "start": "2016-10-01T12:30:00Z",
      "id": "fdTwefoewOEewOIWfgnrgG8=",
      "organizer": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "transparent": false,
      "account_id": "123",
      "type": "event",
      "api": "calendar"
    }

Retrieve an Event 

retrieve an eventGET /accounts/{account_id}/cal/calendars/{calendar_id}/events/{event_id}

custom_properties.private only available for Google Calendar.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "end": "2016-10-01T13:30:00Z",
      "description": null,
      "created": "2016-10-01T06:24:38Z",
      "creator": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "attachments": [],
      "modified": "2016-10-01T07:39:09.420000Z",
      "visibility": null,
      "name": "Event",
      "recurrence": [],
      "recurrence_type": "solo",
      "attendees": [],
      "location": null,
      "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
      "use_default_reminder": false,
      "reminders": [],
      "custom_properties": [
        {
          "key": "color",
          "value": "green",
          "private": true
        }
      ],
      "start": "2016-10-01T12:30:00Z",
      "id": "fdTwefoewOEewOIWfgnrgG8=",
      "organizer": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "transparent": false,
      "account_id": "123",
      "type": "event",
      "api": "calendar"
    }

Update an Event 

update an eventPATCH /accounts/{account_id}/cal/calendars/{calendar_id}/events/{event_id}

To update an event, create a JSON object with any of the following properties:

  • name

  • description

  • start

  • end

  • creator (only supported for google_calendar)

  • organizer

  • attendees

  • location

  • attachments

  • use_default_reminder (only supported for google_calendar)

  • reminders

  • recurrence

  • visibility

  • transparent

  • custom_properties

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "end": "2016-11-01T15:30:00Z",
        "description": "A new description"
    }' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events/fdTwefoewOEewOIWfgnrgG8='

How to RSVP to a calendar event invitation

Example:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "attendees": [{
            "name": "attendee",
            "email": "attendee@company.com",
            "status": "accepted"
        }]
    }' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events/fdTwefoewOEewOIWfgnrgG8='

How to modify custom properties

Assume we already have following custom property in an event.

"custom_properties": [
    {
        "key": "color",
        "value": "green"
    }
]

To create a new custom property.

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "custom_properties": [
            {
                "key": "opacity",
                "value": "0.5"
            }
        ]
    }' \
    'https://api.kloudless.com/v1/accounts/123/cal/calendars/456'

To edit an existed custom property.

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "custom_properties": [
            {
                "key": "color",
                "value": "red"
            }
        ]
    }' \
    'https://api.kloudless.com/v1/accounts/123/cal/calendars/456'

To delete an existed custom property.

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "custom_properties": [
            {
                "key": "color",
                "value": null
            }
        ]
    }' \
    'https://api.kloudless.com/v1/accounts/123/cal/calendars/456'

For Google Calendar, you always need to provide private field with true or false.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "end": "2016-11-01T15:30:00Z",
      "description": "A new description"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "end": "2016-11-01T15:30:00Z",
      "description": "A new description",
      "created": "2016-10-01T06:24:38Z",
      "creator": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "attachments": [],
      "modified": "2016-10-01T07:39:09.420000Z",
      "visibility": null,
      "name": "Event",
      "recurrence": [],
      "recurrence_type": "solo",
      "custom_properties": [
        {
          "key": "color",
          "value": "green",
          "private": true
        }
      ],
      "attendees": [],
      "location": null,
      "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
      "use_default_reminder": false,
      "reminders": [],
      "start": "2016-10-01T12:30:00Z",
      "id": "fdTwefoewOEewOIWfgnrgG8=",
      "organizer": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "transparent": false,
      "account_id": "123",
      "type": "event",
      "api": "calendar"
    }

Delete an Event 

delete an eventDELETE /accounts/{account_id}/cal/calendars/{calendar_id}/events/{event_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/accounts/me/cal/calendars/primary/events/fdTwefoewOEewOIWfgnrgG8=
  • Response  204

Calendar Availability 

Kloudless returns available time slots given a set of calendars, meeting duration time, and preferred meeting times.

Currently, only calendars in the same account are supported, but cross-account calendars are coming soon.

The following services are currently supported:

  • google_calendar

  • outlook_calendar

  • caldav

  • exchange

Check out our UI Tool to schedule a time between your app’s users here: https://github.com/Kloudless/meeting-scheduler

Find Availability 

find availabilityPOST /accounts/{account_id,account_id,...}/cal/availability

To find time ranges that work for an event among multiple participants, provide the following parameters:

  • calendars: An object with data as described below. If not provided, use the primary calendar instead. (Optional)

    • for calendars in the same account:
      • List of Calendar IDs.
    • for cross-account calendars:
      • An JSON object of data with account_id and list of Calendar IDs.
  • meeting_duration: ISO 8601 format for duration. (Required)

  • constraints: An object with constraint values as described below. (Required)

    • time_windows: List of desired time slots with the following values.

      • start: ISO 8601 datetime format

      • end: ISO 8601 datetime format

A list of ranges will be returned with start and end times. Each time range returned indicates that all calendars are available for a meeting for the meeting_duration specified within that range. It is then up to your application to determine the exact start time for the event and to create the event using the Event Creation endpoint.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "calendars": ["fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20="],
        "meeting_duration": "PT1H",
        "constraints": {
            "time_windows": [{
                "start": "2017-05-20T08:00:00+07:00",
                "end": "2017-05-20T12:00:00+07:00"
            },{
                "start": "2017-05-21T08:00:00+07:00",
                "end": "2017-05-21T12:00:00+07:00"
            }]
        }
    }' \
    'https://api.kloudless.com/v1/accounts/123/cal/availability'

This endpoint supports comma-separated Account IDs. Calendars under multiple accounts can be searched by separating the account IDs with commas:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "calendars": {
            "123": ["fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20="],
            "456": ["fQUFNa0FEUTBOR1kxT0daa0xUTTBNamd0TkRKaE5pMDVNMk5sTFRRME9EWTFOV0V3TldJMU53QkdBQUFBQUFBRUFnQ0t6bGYxUnE2MXpvVmsxZ2FlQndCMlYzWDNBOUtqVExZWllrWWFBYy1BQUFBQUFBRUdBQUIyVjNYM0E5S2pUTFlaWWtZYUFjLUFBQUFBQUJ6TEFBQT0="],
        },
        "meeting_duration": "PT1H",
        "constraints": {
            "time_windows": [{
                "start": "2017-05-20T08:00:00+07:00",
                "end": "2017-05-20T12:00:00+07:00"
            },{
                "start": "2017-05-21T08:00:00+07:00",
                "end": "2017-05-21T12:00:00+07:00"
            }]
        }
    }' \
    'https://api.kloudless.com/v1/accounts/123,456/cal/availability'

An example response can be found in the tab below. Note that the windows returned represent ranges in time and not specific time slots for potential events, so will almost always be larger than the duration specified.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "calendars": [
        "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20="
      ],
      "meeting_duration": "PT1H",
      "constraints": {
        "time_windows": [
          {
            "start": "2017-05-20T08:00:00+07:00",
            "end": "2017-05-20T12:00:00+07:00"
          },
          {
            "start": "2017-05-21T08:00:00+07:00",
            "end": "2017-05-21T12:00:00+07:00"
          }
        ]
      }
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "time_windows": [
        {
          "start": "2017-05-20T09:00:00+07:00",
          "end": "2017-05-20T11:15:00+07:00"
        },
        {
          "start": "2017-05-21T09:30:00+07:00",
          "end": "2017-05-21T11:25:00+07:00"
        }
      ],
      "type": "availability",
      "api": "calendar"
    }

Activity Stream 

Activity within a calendar service ranges from creating events and adding attendees to changing start/end times and more. We track the activity data provided by the third-party service. We currently present the following types of activity as Kloudless Event objects via the Kloudless Events API:

  • add: a new object has been created

  • delete: an object has been deleted

  • update: an object has been modified

A Kloudless Event object (not to be confused with Calendar API Events) provides information on activity within a connected account.

See the Events endpoints for more information on supported services, API endpoints, and the format of activity stream data.

List Events 

list eventsGET /accounts/{account_id}/events{?cursor}

The response contains the following fields:

  • objects: List of the events that have taken place. If no events are available, then there are none left to paginate through using the cursor at this time.

  • cursor: A string identifying a location in the stream immediately after the events described in objects.

  • count: Number of events returned.

  • type: Will always be object_list.

  • api: Will always be events.

The returned cursor should be used in subsequent requests so that only events that have not been seen previously are returned.

The remaining attribute used to be available as well but has been deprecated due to limitations with performance and accuracy.

Example Request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/events?cursor=121'
  • Parameters
  • cursor
    string (optional) 

    The last cursor in the event stream that your application has seen. The cursor can also be set to after-auth, which will retrieve events that have occurred after the account was connected. This is useful if prior events are unnecessary.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "count": 1,
        "api": "events",
        "cursor": "121",
        "objects": [{
            "id": "30",
            "account": 123,
            "action": "+",
            "ip": null,
            "modified": "2018-10-18T08:53:28Z",
            "type": "add",
            "user_id": null,
            "metadata": {
                "api": "calendar",
                "type": "event",
                "recurrence_type": "solo",
                "calendar_id": "fa2xvdWRsZXNzQGdtYWlsLmNvbQ==",
                "account_id": "123",
                "id": "fM3NndHRhbWRzamRnOXJvaDU2ZWI4bWoyOTA=",
                "name": "Test Event",
                "description": null,
                "location": null,
                "use_default_reminder": false,
                "reminders": [],
                "visibility": null,
                "created": "2018-10-18T08:53:28Z",
                "modified": "2018-10-18T08:53:28.106000Z",
                "start": "2018-10-19T09:00:00Z",
                "end": "2018-10-19T10:00:00Z",
                "status": "confirmed",
                "attendees": [],
                "attachments": [],
                "organizer": {
                  "id": null,
                  "name": null,
                  "email": "kloudless@gmail.com",
                  "required": true,
                  "resource": false
                },
                "creator": {
                  "id": null,
                  "name": null,
                  "email": "kloudless@gmail.com",
                  "required": true,
                  "resource": false
                }
            }
        }],
        "type": "object_list",
    }