Recurring Events ^ALPHA

Description #

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-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly", "interval": 2 }
    ]
  }
}

Parameters #

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-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly" }
    ],
    "exceptions": {
      "add": [
        { "date": "2024-12-27" },
      ]
    }
  }
}

Common recurrence examples #

Daily

{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2024-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "daily" }
    ]
  }
}

Weekly

{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2024-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly" }
    ]
  }
}

Every weekday

{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2024-12-20T15:30:00Z",
  "end": "2024-12-20T17: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-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly", "interval": 2 }
    ]
  }
}

Monthly

{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2024-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "monthly" }
    ]
  }
}

Yearly

{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2024-12-20T15:30:00Z",
  "end": "2024-12-20T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "yearly" }
    ]
  }
}