Recurring Events ALPHA
Required plan: StarterDescription #
The recurrence
parameter is used to define how an event recurs. It contains a
rules
Array that describe the frequency and interval. This is an array because
some of the underlying calendar models support it, but in practice only one rule
is provided and should be used.
Example Request #
POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "weekly", "interval": 2 }
]
}
}
Parameters #
data_center_url required
The URL for the data center you want to communicate with. Possible choices are:
api-au.cronofy.com
- π¦πΊ Australiaapi-ca.cronofy.com
- π¨π¦ Canadaapi-de.cronofy.com
- π©πͺ Germanyapi-sg.cronofy.com
- πΈπ¬ Singaporeapi-uk.cronofy.com
- π¬π§ United Kingdomapi.cronofy.com
- πΊπΈ United States
Find out more about Cronofy's data centers.
recurrence optional #
Providing the recurrence
parameter will cause the receiving calendar service
to apply a recurrence rule to the event.
Not providing the recurrence
parameter will mean any existing rules are
retained. To remove the recurrence rules from an event you must explicitly
provide an empty array of recurrence rules.
recurrence.rules.frequency required #
A String
value representing the
frequency of recurrence. One of:
daily
weekly
monthly
yearly
recurrence.rules.by_day optional #
An array of String
week days that the
recurrence will generate events for.
This is only valid for use with a weekly
recurrence frequency, and if
omitted the recurrence rule generates occurrences on the same day for each week
it is active.
Valid options are:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
recurrence.rules.interval optional #
An Integer
greater than zero
describing the recurrence interval. Can be thought of “every X” (eg.
“every day”, “every week”, etc).
For example, biweekly needs an interval of 2 to make it “every 2 weeks”.
This can be applied to all frequencies so you can have “every 5 days”, “every 4 weeks”, “every 3 months”, “every 2 years”, and so on.
recurrence.rules.count optional #
An Integer
greater than zero
describing the number of occurrence that should be generated.
For example, “five consecutive days” would be a daily
frequency, with a
count
of 5
.
If not specified, the number of occurrences are effectively infinite.
recurrence.rules.until optional #
A Date
that occurrences should be
generated until. This is inclusive and so if an occurrence falls on the
specified date, that event will be created.
recurrence.exceptions.add optional #
An array of exceptions that should be excluded from the existing series if present.
There can be a maximum of 64 exceptions to a series.
recurrence.exceptions.add.date optional #
The original Date
of an occurrence that
should be removed from the series of events created by the recurrence rule.
For example, this creates a rule generating an event every week, except next week:
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "weekly" }
],
"exceptions": {
"add": [
{ "date": "2024-09-16" },
]
}
}
}
Common recurrence examples #
Daily
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "daily" }
]
}
}
Weekly
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "weekly" }
]
}
}
Every weekday
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{
"frequency": "weekly",
"by_day": [
{"day": "monday"},
{"day": "tuesday"},
{"day": "wednesday"},
{"day": "thursday"},
{"day": "friday"}
]
}
]
}
}
Biweekly
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "weekly", "interval": 2 }
]
}
}
Monthly
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "monthly" }
]
}
}
Yearly
{
"event_id": "recurrence-example",
"summary": "Example",
"start": "2024-09-09T15:30:00Z",
"end": "2024-09-09T17:00:00Z",
"tzid": "Europe/Berlin",
"recurrence": {
"rules": [
{ "frequency": "yearly" }
]
}
}