Back to top

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 outlook_calendar
    • CalDAV caldav

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. If the raw data header is present in the request, all resources returned will also contain a “raw” field that contains the data as represented by the underlying service.

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

  • 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)

  • 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

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/cal/calendars' \
    -XPOST -d '{
        "name": "My Calendar",
        "description": "A calendar for events",
        "location": "San Francisco, CA",
        "timezone": "US/Pacific"
    }'
  • 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

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/123/cal/calendars/456'
  • 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/123/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.

  • id Unique identifier for the event

  • 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

  • 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 Object with details about the event’s reminders for the user account

  • recurrence Object with information about a recurring event

  • 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.
  • raw Underlying object retrieved from the service

  • type Will always be event

  • api Will always be calendar

Person objects have this structure:

  • id profile ID of the person

  • name Name of the person

  • email Email address of the person

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

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

  • Parameters
  • start
    string (required) Default: 2016-01-01T00:00:00Z 

    ISO 8601 timestamp indicating the start of the range of events to retrieve, by event start time.

    end
    string (required) Default: 2016-11-01T20:30:00Z 

    ISO 8601 timestamp indicating the end of the range of events to retrieve, by event end time.

    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": null,
          "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": true
              },
              "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=",
          "reminder": null,
          "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 (required)

  • creator: A Person object describing the creator (required)

  • 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

  • reminder: Object with details about the event’s reminders for the user account

  • recurrence: Object with information about a recurring event

  • visibility: Visibility of the event

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/cal/calendars/456/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"
        },
        "owner": {
                    "name": "Company Owner",
                    "email": "owner@company.com"
        }
    }'
  • 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"
      },
      "owner": {
        "name": "Company Owner",
        "email": "owner@company.com"
      }
    }
  • 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": null,
      "attendees": [],
      "location": null,
      "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
      "reminder": null,
      "start": "2016-10-01T12:30:00Z",
      "id": "fdTwefoewOEewOIWfgnrgG8=",
      "organizer": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "account_id": "123",
      "type": "event",
      "api": "calendar"
    }

Retrieve an Event 

retrieve an eventGET /accounts/{account_id}/cal/calendars/{calendar_id}/events/{event_id}
  • 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": null,
      "attendees": [],
      "location": null,
      "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
      "reminder": null,
      "start": "2016-10-01T12:30:00Z",
      "id": "fdTwefoewOEewOIWfgnrgG8=",
      "organizer": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "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 account, create a JSON object with any of the following properties:

  • name

  • description

  • start

  • end

  • creator

  • organizer

  • attendees

  • location

  • attachments

  • reminder

  • recurrence

  • visibility

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/123/cal/calendars/456'
  • 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": null,
      "attendees": [],
      "location": null,
      "calendar_id": "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=",
      "reminder": null,
      "start": "2016-10-01T12:30:00Z",
      "id": "fdTwefoewOEewOIWfgnrgG8=",
      "organizer": {
        "email": "owner@company.com",
        "id": null,
        "name": "Company Owner"
      },
      "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/123/cal/calendars/456/events/789
  • Response  204

Calendar Availability 

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

Currently, only the default calendar is supported, but multiple calendars and cross-account calendars are coming soon.

The following services are currently supported:

  • google_calendar

  • outlook_calendar

  • caldav

Find Availability 

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

To find a set of available time slots, provide the following parameters:

  • calendars: List of Calendar IDs. Currently uses the default. (Optional)

  • meeting_duration: ISO 8601 format for duration. (Required)

  • constraints: A dictionary of constraint values. (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 available time slots will be returned with start and end times.

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'
  • 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:00:00+07:00"
        },
        {
          "start": "2017-05-21T10:00:00+07:00",
          "end": "2017-05-21T11:00: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) has the following fields:

  • id: unique identifier

  • account: identifier of the associated Account

  • type: one of ‘add’, ‘delete’, or ‘update’

  • metadata: Metadata of the associated Calendar or Event object.

  • api: The API corresponding to the data the event is for. In this case calendar.

See the Events endpoints for more information on supported services. For Calendar API events, the following services are supported:

  • google_calendar

  • outlook_calendar

List Events 

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

The response contains the following fields:

  • objects: List of the events that have taken place.

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

  • count: Number of events returned.

  • remaining: Number of events remaining in the stream.

  • 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.

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
    {
      "total": 1,
      "count": 1,
      "page": 1,
      "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": null,
          "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": true
              },
              "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=",
          "reminder": null,
          "start": "2016-11-01T01:00:00Z",
          "id": "fdTJpb29oamJyZ2NmNWVpcXBwZTQ5NW1hcG8=",
          "organizer": {
            "email": "kloudless@gmail.com",
            "id": null,
            "name": "kloudless inc"
          },
          "account_id": "123",
          "api": "calendar"
        }
      ],
      "type": "object_list",
      "api": "events"
    }