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
- Time Zones How time and time zones are used with the Cronofy API.
- Filtering Events A summary of the event filtering parameters and how they interact.
- Application Calendars An introduction to Application Calendars and how to use them as a drop in replacement for end-user or resource calendars.
- Editing Events How to edit External Events using the Cronofy API