Accessing calendars for the first time.

How to get started with the Cronofy API and quickly read end create events in your calendar.

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 Sandboxto obtain a token that allows you to interact with your own calendar.

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/Chicagoor 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

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

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

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

Also see docs for the Upsert Events endpoint

That’s it!

giphy-2

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

Our full API docs cover the entire API functionality.