Getting started with the Cronofy Calendar API

Cronofy is a single, managed API for all calendar services. Using Cronofy, you continue to reap all the benefits and native features of the calendar APIs for Apple iCloud, Microsoft Exchange, Office 365, Outlook.com and Google without any of the limitations.

In this 10 minute guide we’ll get you started as quickly as possible with the Cronofy Calendar API. This will cover:

Authorization

The very first thing to do is obtain authorization to access a user’s calendars. Cronofy acts as an intermediary between your application and the various calendar services in use.

We act as an OAuth2 provider to your application so API access is via a user specific token. It can be a bit overkill to setup an OAuth2 auth flow for just trying something out so we’ve created the Calendar Sandbox to give you a simple way of interacting with our API for your calendar account.

Once you’ve signed up for a developer account you then use your Calendar Sandbox to obtain a token that allows you to interact with your own calendar.

Connect your Calendar Sandbox

Once you’ve connected your calendar and have the token, it’s time to read on.

Reading Events

The Cronofy API allows you to read all events across all calendars for all providers with one call. The only mandatory parameter is the tzid, ie. time zone identifier, for which you want to read.

The example below is for UTC, but you can also use Europe/Paris, America/Chicago or any identifier in the IANA Time Zone Database.

curl -v -G --header "Authorization: Bearer {YOUR_TOKEN_HERE}" \
  -d 'tzid=Etc/UTC' https://api.cronofy.com/v1/events
cronofy = Cronofy::Client.new(access_token: '{YOUR_TOKEN_HERE}')
events = cronofy.read_events
var cronofy = new CronofyAccountClient("{YOUR_TOKEN_HERE}");
var events = cronofy.GetEvents();
var options = {
    access_token: '{YOUR_TOKEN_HERE}',
    tzid: 'Etc/UTC'
};

cronofy.readEvents(options)
    .then(function (response) {
        var events = response.events;
    });
$cronofy = new Cronofy('', '', '{YOUR_TOKEN_HERE}', '');

$events = $cronofy->read_events(array('tzid' => 'Etc/UTC'));

This will return JSON formatted results similar to this:

{
  "events": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "event_uid": "evt_external_54008b1a4a41730f8d5c6037",
      "summary": "Company Retreat",
      "description": "",
      "start": "2014-09-06",
      "end": "2014-09-08",
      "deleted": false,
      "location": {
        "description": "Beach"
      },
      "participation_status": "needs_action",
      "transparency": "opaque",
      "event_status": "confirmed",
      "categories": [],
      "attendees": [
        {
          "email": "example@cronofy.com",
          "display_name": "Example Person",
          "status": "needs_action"
        }
      ],
      "created": "2014-09-01T08:00:01Z",
      "updated": "2014-09-01T09:24:16Z"
    }
  ]
}

You’ll see that the response is also setup for paging so if there is more than one page you can request the next one by using the url supplied in pages.next_page.

By default the events returned are approximately from 2 weeks prior to 6 months in the future. You can also specify from and to parameters to refine that search.

For example, the following will return events between, and including, September 5, 2015 and September 11, 2015.

curl -v -G --header "Authorization: Bearer {YOUR_TOKEN_HERE}" \
  -d 'tzid=Etc/UTC&from=2015-09-05&to=2015-09-11' https://api.cronofy.com/v1/events
cronofy = Cronofy::Client.new(access_token: '{YOUR_TOKEN_HERE}')
events = cronofy.read_events(from: Date.new(2016, 2, 7), to: Date.new(2016, 2, 15))
var cronofy = new CronofyAccountClient("{YOUR_TOKEN_HERE}");
var builder = new GetEventsRequestBuilder()
                    .From(2015, 9, 5)
                    .To(2015, 9, 11);
var events = client.GetEvents(builder);
var options = {
    access_token: '{YOUR_TOKEN_HERE}',
    tzid: 'Etc/UTC',
    from: '2015-09-05',
    to: '2015-09-11'
};

cronofy.readEvents(options)
    .then(function (response) {
        var events = response.events;
    });
$cronofy = new Cronofy('', '', '{YOUR_TOKEN_HERE}', '');

$params = array(
    'tzid' => 'Etc/UTC',
    'from' => '2015-09-05',
    'to' => '2015-09-11'
);
$events = $cronofy->read_events($params);

Also see docs for the Read Events endpoint

Creating a Calendar Event

The first step is to get the calendar_id for the calendar you want to insert the event into.

curl -v --header "Authorization: Bearer {YOUR_TOKEN_HERE}" \
    https://api.cronofy.com/v1/calendars
cronofy = Cronofy::Client.new(access_token: '{YOUR_TOKEN_HERE}')
events = cronofy.list_calendars
var cronofy = new CronofyAccountClient("{YOUR_TOKEN_HERE}");
var calendars = cronofy.GetCalendars();
cronofy.listCalendars({ access_token: '{YOUR_TOKEN_HERE}'})
    .then(function (response) {
        var calendars = response.calendars;
    });
$cronofy = new Cronofy('', '', '{YOUR_TOKEN_HERE}', '');

$calendars = $cronofy->list_calendars();

This will give you a response similar to this.

{
  "calendars": [
    {
      "provider_name": "google",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
      "calendar_name": "Home",
      "calendar_readonly": false,
      "calendar_deleted": false
    },
    {
      "provider_name": "apple",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_3nkj23wejk1",
      "calendar_name": "Bank Holidays",
      "calendar_readonly": true,
      "calendar_deleted": false
    }
  ]
}

The calendar_id is the internal Cronofy identifier for the calendar. You can then create and event by posting a JSON formatted payload.

To create the follow event in a specific calendar,

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2014-08-05T15:30:00Z",
  "end": "2014-08-05T17:00:00Z",
  "location": {
    "description": "Board room"
  }
}

you would post the following.

curl -v --header "Authorization: Bearer {YOUR_TOKEN_HERE}" \
    --header "Content-Type: application/json" \
    --data "{\"event_id\": \"qTtZdczOccgaPncGJaCiLg\",\"summary\": \"Board meeting\",\"description\": \"Discuss plans for the next quarter.\",\"start\": \"2014-08-05T15:30:00Z\",\"end\": \"2014-08-05T17:00:00Z\",\"location\": {\"description\": \"Board room\"}}" \
    https://api.cronofy.com/v1/calendars/{CALENDAR_ID}/events
cronofy = Cronofy::Client.new(access_token: '{YOUR_TOKEN_HERE}')
new_event = {
  event_id: "qTtZdczOccgaPncGJaCiLg",
  summary: "Board meeting",
  description: "Discuss plans for the next quarter.",
  start: Time.parse("2014-08-05T15:30:00Z"),
  end: Time.parse("2014-08-05T17:00:00Z"),
  location: {
    description: "Board room"
  }
}

cronofy.upsert_event(calendar_id, new_event)
var cronofy = new CronofyAccountClient("{YOUR_TOKEN_HERE}");
var eventBuilder = new UpsertEventRequestBuilder()
                        .EventId("uniq-id")
                        .Summary("Event summary")
                        .Description("Event description")
                        .Start(2015, 10, 20, 17, 00)
                        .End(2015, 10, 20, 17, 30)
                        .Location("Meeting room");

cronofy.UpsertEvent(calendarId, eventBuilder);
var options = {
    access_token: '{YOUR_TOKEN_HERE}',
    event_id: "qTtZdczOccgaPncGJaCiLg",
    summary: "Board meeting",
    description: "Discuss plans for the next quarter.",
    start: "2015-11-25T15:30:00Z",
    end: "2015-11-25T17:00:00Z",
    location: {
        description: "Board room"
    }
};

cronofy.createEvent(options)
    .then(function () {
        // Success
    });
$cronofy = new Cronofy('', '', '{YOUR_TOKEN_HERE}', '');

$params = array(
    'calendar_id' => $calendarId,
    'event_id' => 'qTtZdczOccgaPncGJaCiLg',
    'summary' => 'Board meeting',
    'description' => 'Discuss plans for the next quarter.',
    'start' => '2015-11-25T15:30:00Z',
    'end' => '2015-11-25T17:00:00Z'
);

$cronofy->upsert_event($params);

Also see docs for the Upsert Events endpoint

That’s it!

you're on your way

Hopefully this guide has given you enough of a heads up to get you started.

Our full API docs cover the entire API functionality.

We’re also more than happy to help directly, just email support@cronofy.com

Get started with our Calendar API

Create an account

It's free

Join our developer mailing list

* indicates required