About calendars

Users often rely on multiple calendars to keep their schedules organized. A common example is maintaining one calendar for professional commitments, such as meetings or project deadlines, and another for personal activities like family events or hobbies. This separation helps users better manage their time and avoid mixing unrelated events. Those kinds of calendars have is_owner_by_user = true.

Beyond their own calendars, users can also subscribe to shared calendars. These are especially useful in collaborative environments. For instance, a colleague may share their calendar in read-only mode so that others can check availability before scheduling a meeting.

Shared calendars can also be collaborative: multiple users may be granted write access, allowing each of them to add, modify, or remove events. This makes shared calendars an essential tool for teams, families, or organizations that need a unified view of schedules.

Get calendars

To list all calendars (owned and subscribed to), use List all Calendars method.

const { data } = await calendarApi.getCalendarsList({
  path: {
    account_id: "acc_123456789",
  },
  query: {
    limit: 20,
  },
});

calendars = calendar_api.get_calendars_list(
    "acc_123456789",
    limit=20,
)

curl --request GET \
     --url https://api.unipile.com/v2/account_id/calendars \
     --header 'accept: application/json'

To get a specific calendar from the list, use Get a Calendar method and provide the calendar ID.

const { data } = await calendarApi.getCalendar({
  path: {
    account_id: "acc_123456789",
    calendar_id: "calendar_id",
  },
});

calendar = calendar_api.get_calendar("acc_123456789", "calendar_id")

curl --request GET \
     --url https://api.unipile.com/v2/account_id/calendars/calendar_id \
     --header 'accept: application/json'

Create a calendar

To create a new calendar for the account owner, use Create a Calendar method and provide a name and an optional description.

You cannot create shared calendars with Unipile.

const { data } = await calendarApi.createCalendar({
  path: {
    account_id: "acc_123456789",
  },
  body: {
    name: 'My Calendar'
  },
});

calendar = calendar_api.create_calendar(
    "acc_123456789",
    {"name": "My Calendar"},
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/calendars \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "My calendar"
}
'

Edit a calendar

To edit the name or description of a calendar, use Update a Calendar method and provide fields to be edited.

const { data } = await calendarApi.updateCalendar({
  path: {
    account_id: "acc_123456789",
    calendar_id: "calendar_id",
  },
  body: {
    name: 'My Calendar'
  },
});

calendar = calendar_api.update_calendar(
    "acc_123456789",
    "calendar_id",
    {"name": "My Calendar"},
)

curl --request PATCH \
     --url https://api.unipile.com/v2/account_id/calendars/calendar_id \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "My calendar"
}
'

Delete a calendar

To delete a calendar, use Delete a Calendar method and provide the Calendar ID.

❗️
Provider limitations

You cannot delete the default calendar of an account.

❗️
Important side effects
Deleting a calendar will also permanently delete all its events.

await calendarApi.deleteCalendar({
  path: {
    account_id: "acc_123456789",
    calendar_id: "calendar_id",
  },
});

calendar_api.delete_calendar("acc_123456789", "calendar_id")

curl --request DELETE \
     --url https://api.unipile.com/v2/account_id/calendars/calendar_id