Calendars & Events

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

  • Getting authorization to access a calendar
  • Reading events
  • Creating your first event

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.

Once you’ve signed up for a developer account, you can create an application.

With your application created, you will be able to connect your calendar by following the OAuth journey.

Once you’ve connected your calendar, you will be able to view your access token and you are ready to start making API calls.

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_ACCESS_TOKEN_HERE}" \
  -d 'tzid=Etc/UTC' https://api.cronofy.com/v1/events
cronofy = Cronofy::Client.new(access_token: '{YOUR_ACCESS_TOKEN_HERE}')
events = cronofy.read_events
var cronofy = new CronofyAccountClient("{YOUR_ACCESS_TOKEN_HERE}");
var events = cronofy.GetEvents();
var options = {
    access_token: '{YOUR_ACCESS_TOKEN_HERE}',
    tzid: 'Etc/UTC'
};

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

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

cronofy = pycronofy.Client(access_token="{YOUR_ACCESS_TOKEN_HERE}")
events = cronofy.read_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": "2023-06-08",
      "end": "2023-06-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": "2023-06-04T08:00:01Z",
      "updated": "2023-06-04T09: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, 2023-06-04 and 2023-06-09.

curl -v -G --header "Authorization: Bearer {YOUR_ACCESS_TOKEN_HERE}" \
  -d 'tzid=Etc/UTC&from=2023-06-04&to=2023-06-09' https://api.cronofy.com/v1/events
cronofy = Cronofy::Client.new(access_token: '{YOUR_ACCESS_TOKEN_HERE}')
events = cronofy.read_events(from: Date.new(2023, 6, 4), to: Date.new(2023, 6, 9))
var cronofy = new CronofyAccountClient("{YOUR_ACCESS_TOKEN_HERE}");
var builder = new GetEventsRequestBuilder()
                    .From(2023, 6, 4)
                    .To(2023, 6, 9);
var events = client.GetEvents(builder);
var options = {
    access_token: '{YOUR_ACCESS_TOKEN_HERE}',
    tzid: 'Etc/UTC',
    from: '2023-06-04',
    to: '2023-06-09'
};

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

$params = array(
    'tzid' => 'Etc/UTC',
    'from' => '2023-06-04',
    'to' => '2023-06-09'
);
$events = $cronofy->read_events($params);
import pycronofy

cronofy = pycronofy.Client(access_token="{YOUR_ACCESS_TOKEN_HERE}")
events = cronofy.read_events(
    from_date='2023-06-04',
    to_date='2023-06-09',
    tzid='Etc/UTC')

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_ACCESS_TOKEN_HERE}" \
    https://api.cronofy.com/v1/calendars
cronofy = Cronofy::Client.new(access_token: '{YOUR_ACCESS_TOKEN_HERE}')
calendars = cronofy.list_calendars
var cronofy = new CronofyAccountClient("{YOUR_ACCESS_TOKEN_HERE}");
var calendars = cronofy.GetCalendars();
cronofy.listCalendars({ access_token: '{YOUR_ACCESS_TOKEN_HERE}'})
    .then(function (response) {
        var calendars = response.calendars;
    });
$cronofy = new Cronofy('', '', '{YOUR_ACCESS_TOKEN_HERE}', '');

$calendars = $cronofy->list_calendars();
import pycronofy

cronofy = pycronofy.Client(access_token="{YOUR_ACCESS_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": "2023-06-04T15:30:00Z",
  "end": "2023-06-04T17:00:00Z",
  "location": {
    "description": "Board room"
  }
}

you would post the following.

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

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

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

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

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

$cronofy->upsert_event($params);
import pycronofy

cronofy = pycronofy.Client(access_token="{YOUR_ACCESS_TOKEN_HERE}")
event = {
    'event_id': "qTtZdczOccgaPncGJaCiLg",
    'summary': "Board meeting",
    'description': "Discuss plans for the next quarter.",
    'start': "2023-06-04T15:30:00Z",
    'end': "2023-06-04T17:00:00Z",
    'location': {
        'description': "Board room"
    }
}
cronofy.upsert_event(calendar_id=calendar_id, event=event)

Creating an all-day event #

To create an all-day event, you just pass the start and end values as ISO 8601 Dates.

You should note that the date value for end operates in the same way as for time in that it’s exclusive. i.e. the event ends just before the end time. The date value for end is always the day after the end of the all-day event period.

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Away for off-site",
  "description": "Discuss plans for the next quarter.",
  "start": "2023-06-04",
  "end": "2023-06-05",
  "tzid": "America/Chicago",
  "location": {
    "description": "Board room"
  }
}

you would post the following:

curl -v --header "Authorization: Bearer {YOUR_ACCESS_TOKEN_HERE}" \
    --header "Content-Type: application/json" \
    --data "{\"event_id\": \"qTtZdczOccgaPncGJaCiLg\",\"summary\": \"Away for off-site\",\"description\": \"Discuss plans for the next quarter.\",\"start\": \"2023-06-04\",\"end\": \"2023-06-05\",\"location\": {\"description\": \"Board room\"}}" \
    https://api.cronofy.com/v1/calendars/{CALENDAR_ID}/events
cronofy = Cronofy::Client.new(access_token: '{YOUR_ACCESS_TOKEN_HERE}')
new_event = {
  event_id: "qTtZdczOccgaPncGJaCiLg",
  summary: "Away for off-site",
  description: "Discuss plans for the next quarter.",
  start: Date.new(2023, 6, 4),
  end: Date.new(2023, 6, 5),
  location: {
    description: "Board room"
  }
}

cronofy.upsert_event(calendar_id, new_event)
var cronofy = new CronofyAccountClient("{YOUR_ACCESS_TOKEN_HERE}");
var eventBuilder = new UpsertEventRequestBuilder()
                        .EventId("qTtZdczOccgaPncGJaCiLg")
                        .Summary("Away for off-site")
                        .Description("Event description")
                        .Start(2023, 6, 4)
                        .End(2023, 6, 5)
                        .TimeZoneId("America/Chicago")
                        .Location("Meeting room");

cronofy.UpsertEvent(calendarId, eventBuilder);
var options = {
    access_token: '{YOUR_ACCESS_TOKEN_HERE}',
    event_id: "qTtZdczOccgaPncGJaCiLg",
    summary: "Away for off-site",
    description: "Discuss plans for the next quarter.",
    start: "2023-06-04",
    end: "2023-06-05",
    tzid: "America/Chicago",
    location: {
        description: "Board room"
    }
};

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

$params = array(
    'calendar_id' => $calendarId,
    'event_id' => 'qTtZdczOccgaPncGJaCiLg',
    'summary' => 'Away for off-site',
    'description' => 'Discuss plans for the next quarter.',
    'start' => '2023-06-04',
    'end' => '2023-06-05',
    'tzid' => 'America/Chicago'
);

$cronofy->upsert_event($params);
import pycronofy

cronofy = pycronofy.Client(access_token="{YOUR_ACCESS_TOKEN_HERE}")
event = {
    'event_id': "qTtZdczOccgaPncGJaCiLg",
    'summary': "Away for off-site",
    'description': "Discuss plans for the next quarter.",
    'start': "2023-06-04",
    'end': "2023-06-05",
    'tzid': "America/Chicago",
    'location': {
        'description': "Board room"
    }
}
cronofy.upsert_event(calendar_id=calendar_id, event=event)

Also see docs for the Upsert Events endpoint

In This Section