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 begin making requests to the Calendar API endpoints listed below.

We support the following services denoted by the friendly name and identifier:

• Calendar Services
  • Google Calendar: google_calendar
  • Outlook Calendar: outlook_calendar
  • CalDAV: caldav
  • Exchange Server 2013+: exchange
  • iCloud Calendar: icloud_calendar

We support the following endpoints and their corresponding unified objects:

• Calendar: calendar

• Event: event

• Contact: contact

Please see the specific resource documentation for what attributes are unified.

Kloudless object attributes that are absent in the upstream service will be null when retrieved, and ignored when sent in create/update requests.

In addition, we can provide the original JSON response from the upstream service, which we call raw data. Please set the raw data header option when performing API requests, and the server will return the raw data in the the JSON response object under the raw key field.

Similarly, raw data can be sent directly to the upstream service via the API when creating or updating objects. This is primarily for attributes that are not unified in the Kloudless APIs. The request body must contain a nested JSON object with the upstream attribute names and values. Please see the example below:

javascript
{
    "raw": {
        "object": {
            ...
            "upstream-name": "upstream-values",
            ...
        }
    }
}

We define this nested object with the shorthand: raw -> object.

We’ve included links for the raw -> object mappings for each service below:

• google_calendar (Raw Calendar Object, Raw Event Object)

• outlook_calendar (Raw Calendar Object, Raw Event Object)

We also support two additional endpoints that are unique to Kloudless:

• Find Availability Find available time slots for calendars with specific time constraints.

• Activity Monitoring Retrieve the latest activity for a calendar for sync, automation, or other use cases.

Quickstart 

Begin by connecting a user’s account using the Kloudless OAuth authentication endpoints. You can then retrieve their primary calendar’s events by using the URL path /accounts/me/cal/calendars/primary/events with a specific start and end time.

• Monitor any changes to the user’s calendar via the Activity Stream to implement features such as calendar sync. See the Google Calendar Quick Start guide for an example of how this can be done.

• Find calendar availabilities to schedule meetings easily with the /availability endpoint.

• You can also use our Meeting Scheduler UI Tool to let your users schedule meetings within your app: https://github.com/Kloudless/meeting-scheduler

Calendars 

A Calendar object contains metadata about a user’s online calendar and 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.

• account_id The ID of the account that the calendar is associated with.

• name Name of the calendar (required).

• description Additional details about the calendar. (only supported for google_calendar and caldav).

• location Geographic location of the calendar as free-form text. (only supported for google_calendar).

• timezone The time zone of the calendar (IANA Time Zone Database name. Only supported for google_calendar and caldav).

• raw Underlying object retrieved from the service. exchange only returns the raw ID.

• type Will always be calendar.

• api Will always be calendar.

• href The absolute URL to get the object’s metadata.

List Calendars 

Create a Calendar 

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

Retrieve a Calendar 

Update a Calendar 

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'

Delete a Calendar 

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

Events 

An Event object represents metadata about an entry on a user’s online calendar. Event objects are commonly associated with a title, start and end times, attendees, and frequency.

An event has the following attributes:

• id Unique identifier for the event.

• account_id The ID of the account that the event is associated with.

• ical_uid A read-only unique identifier for the event as defined in RFC 5545. This identifier is unique across different calendars, which is valuable when accessing multiple users’ calendars at once, especially with admin accounts. Note that Outlook Calendar does not respect this attribute for events created by an external organizer, such as a Google Calendar user, and assigns its own ical_uid instead internal to Office 365. However, events across users within the same calendaring system will maintain the same ical_uid.

• 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 Details of the event. May be text or HTML. When creating or updating events with an HTML description in Outlook and Exchange, ensure the first character is < and the last character is >. This ensures the description is considered to be HTML. When reading events, Kloudless returns text descriptions for Outlook Calendar. To return HTML descriptions for Outlook Calendar, set the raw header X-Kloudless-Raw-Headers: {"Prefer": "outlook.body-content-type=\"html\""}. Google Calendar automatically renders text and HTML as appropriate.

• created ISO 8601 timestamp indicating when the event was created.

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

• all_day Only available for google_calendar and outlook_calendar. true if it’s an all-day event; false otherwise. Defaults to false. If true, start and end should be ISO 8601 dates rather than timestamps, such as "2020-01-01". If false, start and end should be ISO 8601 timestamps, such as "2020-01-01T00:00:00Z".

  Create an all-day event by setting all_day to true and ensuring the the start date is inclusive and the end date is exclusive. For example, an all-day event that occurs on both 2020-01-01 and 2020-01-02 would need end to be set to "2020-01-03".

• start ISO 8601 timestamp or date indicating when the event starts (inclusive). The format depends on all_day although either is accepted during event creation/updates.

• start_time_zone The IANA time zone database name that corresponds to the start time’s time zone. For example, America/Los_Angeles. This field isn’t supported for all-day events. If the value of this field is not set, the user’s default time zone is used if known (only supported for google_calendar, outlook_calendar, exchange, caldav, and icloud_calendar).

• end ISO 8601 timestamp or date indicating when the event ends (exclusive). The format depends on all_day although either is accepted during event creation/updates.

• end_time_zone The IANA time zone database name that corresponds to the end time’s time zone. For example, America/Los_Angeles. This field isn’t supported for all-day events. If the value of this field is not set, the user’s default time zone is used if known (only supported for google_calendar, outlook_calendar, exchange, caldav, and icloud_calendar).

• original_start A read-only ISO 8601 timestamp or date present for recurring events that represents the time that the event was originally set up to start at, based on the recurrence data in the master event with ID recurring_master_id. Only supported for google_calendar.

• original_start_time_zone A read-only IANA time zone database name that corresponds to the original_start time’s time zone. For example, America/Los_Angeles. This field isn’t supported for all-day events.

• organizer A Person object describing the organizer.

• on_organizer_calendar A boolean value indicating whether this Event represents the calendar event on the calendar of its organizer, rather than the calendar of an attendee. See ical_uid for an ID that is consistent across all calendars the event is scheduled on. Only supported for google_calendar and outlook_calendar.

• 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) When to show the reminder, expressed as minutes before the event start time. (only supported for outlook_calendar and exchange) 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.
  • icloud_calendar: no limit, however all calendar and reminder data (not including attachments) cannot exceed 1GB

• recurrence A list of Recurrence objects that contain information about a recurring event. The Recurrence object format is documented below this section.

• recurrence_type

  • solo: A stand-alone event

  • recurring: A recurring event

  • recurring_master: The primary/master event in the series of recurring events

    Please note that for some caldav servers, the recurrence_type returned may be inconsistent when performing a list events operation. (Specifically, it is possible that the first event in a series of recurrences is marked as "recurrence_type": "solo", which is incorrect.)

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

• online_meeting An Online Meeting object, representing online conference information for the event. See below for the structure of an Online Meeting object.

  The following services are currently supported:

  • google_calendar
  • outlook_calendar

• visibility Visibility of the event (only supported for google_calendar)

  • 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} (only supported for google_calendar, outlook_calendar, and exchange).

• raw Underlying object retrieved from the service. exchange only returns the raw ID.

• type Will always be event.

• api Will always be calendar.

• href The absolute URL to get the object’s metadata.

Reminder objects have the following structure:

• minutes When to show the reminder, expressed as minutes before the event start time.

• 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
  • icloud_calendar: email, popup

• popup The description present in the pop-up. Only supported for caldav and icloud_calendar. Required for caldav and icloud_calendar if the method is popup.

• email Email object. Only supported for caldav and icloud_calendar. Required for caldav and icloud_calendar 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

Recurrence objects have the following structure:

• rrule An RRULE string in the format described by RFC5545.

  Outlook Calendar and Exchange limitations: The recurrence rule properties available vary based on the frequency of the recurring event as shown in the table below. The rows represent the properties available when specifying a recurrence pattern with a specific frequency:

  DAILY	WEEKLY	MONTHLY	MONTHLY (relative)	YEARLY	YEARLY (relative)
  INTERVAL	INTERVAL	INTERVAL	INTERVAL	INTERVAL	INTERVAL
  COUNT	COUNT	COUNT	COUNT	COUNT	COUNT
  UNTIL	UNTIL	UNTIL	UNTIL	UNTIL	UNTIL
  	BYDAY	BYMONTHDAY	BYDAY	BYMONTHDAY	BYDAY
  	WKST		BYSETPOS	BYMONTH	BYMONTH
  					BYSETPOS

  Frequencies and properties not listed above are unsupported.

  A Timezone or UTC offset within an RRULE is unsupported and will be ignored. Outlook will use the event’s timezone when expanding the Recurrence pattern.

  The data model used by outlook_calendar and exchange is not in the RRULE format and instead uses an object called a patternedRecurrence to define the pattern and range of recurring events. This means that some RRULE properties are not supported, such as HOURLY, EXDATE, and others. You can read more about Outlook’s implementation here.

Person objects have the following structure:

• id profile ID of the person.

• name Name of the person.

• email Email address of the person.

• status Status of the person’s response to the meeting invitation. One of accepted, declined, tentative, or pending. Present for Person objects included in attendees. May not be present if unavailable. (only supported for google_calendar, outlook_calendar, and exchange)

• required A boolean indicating whether this is a required attendee. Present for Person objects included in attendees.

• resource Read-only. A boolean indicating whether the attendee is a resource. Present for Person objects included in attendees.

File objects have the following 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 update a Google Calendar event with custom properties.

  For more info, please refer to Google Calendar Event extendedProperties

Online Meeting objects have the following structure:

• conference_id (read-only) A string with the conference ID of the Online Meeting. The ID is provided as received from the upstream service, without additional encoding.

• online_meeting_provider (required) A string representing a code for this meeting’s provider, specified by the upstream service.

  For google_calendar, possible values are:

  • eventHangout: Hangouts for consumers (hangouts.google.com)
  • eventNamedHangout: class Hangouts for Google Workspace (formerly G Suite) users (hangouts.google.com)
  • hangoutsMeet: Google Meet (meet.google.com)
  • addOn: Third-party conference providers. Please see the Google Calendar Event docs for more information.

  For outlook_calendar, possible values are:

  • teamsForBusiness: Microsoft Teams meeting
  • skypeForBusiness: Skype for Business call
  • skypeForConsumer: Skype call (consumer)
  • unknown: Other (the default for outlook_calendar events). Please see the Outlook Calendar Event docs for more information.

• entry_points An array of Online Meeting Entry Point objects describing how to access the online conference. Read-only for outlook_calendar. Writable for google_calendar when adding a new Online Meeting, but not updatable.

• notes (only supported for google_calendar) A string with any notes associated with the Online Meeting.

• signature (only supported for google_calendar) A string with the signature of the Online Meeting, generated by the upstream service.

Online Meeting Entry Point objects have the following structure:

• uri (required) A string with the URI of the this Entry Point. May be an HTTP URI for video meetings, a telephone URI beginning with tel: for dial-in numbers, or an SIP URI beginning with sip: for joining a conference over SIP. Examples:

  • https://meet.google.com/xxx-yyy-zzz
  • tel:+1-323-555-0166
  • tel:+12345678900,,,123456789;1234
  • sip:12345678@myprovider.com

• entry_point_type A string describing the type of Entry Point. Can be one of the following values:

  • video (the default): Joining a conference over HTTP.
  • phone: Joining a conference by dialing a telephone number.
  • sip: Joining a conference over SIP.
  • more: Further ways to join a conference, such as additional phone numbers.

• meeting_code (optional) The meeting code for the Online Meeting. Only applicable for google_calendar.

• access_code (optional) The access code for the Online Meeting. Only applicable for google_calendar.

• passcode (optional) The passcode for the Online Meeting. Only applicable for google_calendar.

• password (optional) The password for the Online Meeting. Only applicable for google_calendar.

• pin (optional) The PIN for the Online Meeting. Only applicable for google_calendar.

Of the fields meeting_code, access_code, passcode, password, and pin, only the ones that match the conference provider’s terminology and are present are populated by google_calendar. Similarly, only the appropriate fields should be populated when creating a google_calendar event, if needed. This enables a developer’s application to use the appropriate terminology when displaying and accepting the conference call’s details.

Event Notifications ¶

An email notification will be sent to all attendees when an event is created, updated, or deleted. However, if only the attendees field is updated, then only specific attendees being added or deleted will receive any notification. Currently supported for 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’s 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 notifications for.

List Events 

Create an Event 

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",
        "raw": {
            "object": {
                "importance": "low"
            }
        }
    }'

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events' \
    -d '{
        "name": "Every day for ten days",
        "start": "2019-04-10T10:00:00Z",
        "end": "2019-04-10T11:00:00Z",
        "recurrence": [{"rrule": "RRULE:FREQ=DAILY;COUNT=10"}]
    }'

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events' \
    -d '{
        "name": "Engineering team meeting",
        "start": "2021-04-10T10:00:00Z",
        "end": "2021-04-10T11:00:00Z",
        "online_meeting": {
          "online_meeting_provider": "hangoutsMeet"
        }
    }'

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events' \
    -d '{
        "name": "Engineering team meeting",
        "start": "2021-04-10T10:00:00Z",
        "end": "2021-04-10T11:00:00Z",
        "online_meeting": {
          "online_meeting_provider": "addOn",
          "entry_points": [
            {
                "uri": "https://example.com/meeting-ABC-123",
                "entry_point_type": "video",
                "password": "fake_password"
            },
            {
                "uri": "tel:+12345678900;1234",
                "entry_point_type": "phone"
            },
            {
                "uri": "sip:12345678@myprovider.com",
                "entry_point_type": "sip"
            }
          ]
        }
    }'

Retrieve an Event 

Update an Event 

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='

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='

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

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/me/cal/calendars/primary/events/fdTwefoewOEewOIWfgnrgG8='

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

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

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "online_meeting": {
          "online_meeting_provider": "hangoutsMeet"
        }
    }' \
    'https://api.kloudless.com/v1/accounts/me/cal/calendars/primary/events/fdTwefoewOEewOIWfgnrgG8='

Delete an Event 

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

Contacts 

Currently supported for:

• google_calendar

• outlook_calendar

• exchange

A Contact object represents metadata about a user’s online contact. A contact has the following attributes:

• id Unique identifier for this contact.

• name A contact’s name. (read-only)

• name_details A JSON object with the following attributes:

  • given: Given name
  • family: Family name
  • full: Full name (read-only)

• birthday ISO 8601 date indicating the contact’s birthday

• organizations A list of Organization objects describing the contact’s organization. An Organization object has the following attributes:

  • type: One of work, school, or other.
  • name: The name of the organization. (required)
  • department: The contact’s department at the organization.
  • title: The contact’s job title at the organization.
  • location: The location of the organization where the contact works at.

• created ISO 8601 timestamp indicating when the contact was created

• emails A list of Email objects describing the contact’s email addresses. An Email object has the following attributes:

  • type: One of home, work, or other.
  • value: The email address. (required)
  • primary: A boolean indicating whether the email is the primary address. (read-only)

• gender The contact’s gender, one of male, female, other, or unknown.

• initials The contact’s initials.

• modified ISO 8601 timestamp indicating when the contact was last modified.

• phones A list of Phone objects describing the contact’s phone numbers. A Phone object has the following attributes:

  • type: One of home, work, mobile, or other.
  • value: The phone number. (required)
  • primary: A boolean indicating whether the phone is primary number. (read-only)

• relationships A list of Relation objects describing the contact’s relationship with another contact. A Relation object has the following attributes:

  • name: The name of the other contact this relation refers to. (required)
  • type: One of child, spouse, or other.

• addresses A list of Address objects describing the contact’s address. An Address object has the following attributes:

  • type: One of home, work, or other.
  • street: The street address.
  • city: The city of the address.
  • state: The state of the address.
  • country: The country of the address.
  • postal_code: The postal code of the address.

• websites A list of websites associated with the contact.

• raw Underlying object retrieved from the upstream service.

• type Will always be contact.

• api Will always be contact.

• href The absolute URL to get the object’s metadata.

List Contacts 

Create a Contact 

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/contact/contacts' \
    -XPOST -d '{
        "name_details": {
            "given": "Walter",
            "family": "Bishop"
        },
        "birthday": "1946-08-20",
        "organizations": [
            {
                "name": "Kloudless",
                "title": "Research Scientist"
            }
        ],
        "emails": [
            {
                "type": "work",
                "value": "hello@kloudless.com"
            }
        ],
        "relationships": [
            {
                "name": "Peter Bishop",
                "type": "child"
            }
        ],
        "addresses": [
            {
                "type": "home",
                "street": "2054 University Ave #200",
                "city": "Berkeley",
                "state": "CA",
                "country": "US",
                "postal_code": "94704"
            },
            {
                "type": "work",
                "street": "14F, No.460 Sec.4, Xinyi Rd.",
                "city": "Xinyi District",
                "state": "Taipei City",
                "country": "TW",
                "postal_code": "110"
            }
        ],
        "websites": [
            "https://github.com/Kloudless",
            "https://kloudless.com"
        ]
    }'

Retrieve a Contact 

Update a Contact 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "birthday": "1946-08-20",
        "organizations": [
            {
                "name": "Kloudless",
                "title": "Research Scientist"
            }
        ],
        "emails": [
            {
                "type": "work",
                "value": "hello@kloudless.com"
            }
        ]
    }' \
    'https://api.kloudless.com/v1/accounts/me/contact/contacts/FytHKX4ltWzfKRJsvh5Ii9Uh7fPBkkXBKjIjOU-sx7CY'

Delete a Contact 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/contact/contacts/FytHKX4ltWzfKRJsvh5Ii9Uh7fPBkkXBKjIjOU-sx7CY

Accessing Co-worker Calendars 

Users using Google Workspace (formerly G Suite), Office 365, and Exchange Server commonly need to schedule events with other users in their tenant. This requires checking those users’ availability on their respective primary calendars.

To help with this, Kloudless provides mechanisms to both obtain org-wide access to data in a tenant via an admin account as well as simply check other calendars in an organization via any regular user’s account.

The following steps demonstrate how to retrieve other users’ calendars:

1. List all users via the Team API’s Users endpoint, or retrieve a specific known user’s metadata.

2. Each user’s metadata includes a calendar_id attribute. If the authenticated user has access to the calendar, its events can be retrieved as usual via the List endpoint.

The Kloudless admin OAuth flow usually grants access to the Team API as documented in the Team API docs, but Kloudless makes an exception listing and retrieving user metadata since calendar services like Google Calendar make this information accessible to regular users.

Outlook calendar does require that the user be authenticated as an admin prior to viewing others’ calendars, however. This then enables access to list all users via the Team API. If this isn’t feasible, users can still always list calendars that they’ve subscribed to, or invite users to events by their email address without specifically checking their availability.

Calendar availability 

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

Currently supported for:

• google_calendar

• outlook_calendar

• caldav

• icloud_calendar

• exchange

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

Find Availability 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "calendars": ["fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20="],
        "meeting_duration": "PT1H",
        "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'

curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "calendars": {
            "123": ["fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20="],
            "456": ["fQUFNa0FEUTBOR1kxT0daa0xUTTBNamd0TkRKaE5pMDVNMk5sTFRRME9EWTFOV0V3TldJMU53QkdBQUFBQUFBRUFnQ0t6bGYxUnE2MXpvVmsxZ2FlQndCMlYzWDNBOUtqVExZWllrWWFBYy1BQUFBQUFBRUdBQUIyVjNYM0E5S2pUTFlaWWtZYUFjLUFBQUFBQUJ6TEFBQT0="],
        },
        "meeting_duration": "PT1H",
        "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'

Activity Monitoring 

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 provide the following types of activity as Kloudless Activity objects via the Kloudless Activity API:

• add: a new object has been created

• delete: an object has been deleted

• update: an object has been modified

Details and metadata about each activity occurring in a connected account is provided in the Kloudless Activity object.

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

Activity API required: These endpoints require your Kloudless subscription to include access to the Activity API.

List Activity 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/default/activity?cursor=121'

Resources 

A Resource represents a shared resource that users can reserve, such as a meeting room, car, equipment, or any other item or space users might need to schedule a time to use.

Currently supported for:

• google_calendar

• outlook_calendar

• exchange

A Resource has the following attributes:

• id Unique identifier for the resource.

• name Name of the resource.

• description Additional details about the resource.

• email The resource’s email address. Use this when booking calendar events to reserve the resource for the duration of the event.

• calendar The resource’s calendar ID. Use this to check its availability or retrieve its schedule.

• category The type of resource. Can be either:

  • room: Represents a meeting room.
  • other: Represents a resource other than a meeting room.

• raw Underlying object retrieved from the service.

• type Will always be resource.

• api Will always be calendar.

Not all services provide information for all Resource attributes. For example, Google Workspace (formerly G Suite) provides data for all the listed attributes, whereas Office 365 only provides the Resource’s (meeting room’s) email address.

List Resources