Back to top

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)

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

  • 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"
        },
        {
          "description": null,
          "name": "Contacts",
          "location": null,
          "timezone": "America/Los_Angeles",
          "id": "fI2NvbnRhY3RzQGdyb3VwLnYuY2FsZW5kYXIuZ29vZ2xlLmNvbQ==",
          "account_id": "123"
        },
        {
          "description": null,
          "name": "Holidays in United States",
          "location": null,
          "timezone": "America/Los_Angeles",
          "id": "fZW4udXNhI2hvbGlkYXlAZ3JvdXAudi5jYWxlbmRhci5nb29nbGUuY29t",
          "account_id": "123"
        }
      ],
      "page": "1"
    }

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"
    }

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"
    }

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"
    }

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

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) Default: 1 

    The page to retrieve. If provided with a value returned from a previous response, the next page of content from the previous query will be retrieved.

    page must be an identifier.

  • 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"
        }
      ]
    }

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"
    }

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"
    }

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"
    }

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

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.

See the Events endpoints for more information on supported services.

List Events 

list eventsGET /accounts/{account_id}/events{?cursor}
  • 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"
        }
      ]
    }