Application Calendars

If you're building an application that requires scheduling for venues, properties, or any resource not tied to a specific person's calendar, Cronofy’s Application Calendars offer a flexible solution. They function as dedicated calendars within the Cronofy ecosystem, allowing you to leverage Cronofy's scheduling tools without the need for a "real" mailbox as a data store.

By using Application Calendars, you can seamlessly integrate scheduling functionality for various use cases, such as booking meeting rooms, managing equipment availability, or coordinating events at specific locations. This guide will walk you through creating and managing Application Calendars, adding events, and utilizing them with Cronofy's scheduling functions, helping you extend your application's scheduling capabilities efficiently.

Creating an Application Calendar

To create an Application Calendar, you specify the application_calendar_id so it operates as an upsert operation:

Example request

POST /v1/application_calendars HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "client_id": {CLIENT_ID},
  "client_secret": {CLIENT_SECRET},
  "application_calendar_id": "my-unique-string"
}

You can then retrieve the calendar’s details as needed by using the same application_calendar_id for subsequent calls to the application_calendars endpoint. The response will include important information, such as the calendar’s access_token which is necessary for utilising Cronofy’s scheduling functionality with that calendar.

The application_calendar_id can be linked back to the meeting venue on the integrator’s side. This way, you can easily tie the Application Calendar to what it is managing availability for.

💡 The Application Calendar’s ID can be defined by the integrator and can be any string - for example, a GUID (globally unique identifier) or a numeric value.

Adding Events to Application Calendars

The process of creating events in an Application Calendar is the same as with user accounts. First, you retrieve the calendar_id via the List Calendars endpoint (you’ll need the access_token from the step above):

Example request

GET /v1/calendarsHTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

Using the calendar_id and the access_token, you can then proceed with a call to create the event:

POST /v1/calendars/{calendar_id}/events HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2024-10-26T15:30:00Z",
  "end": "2024-10-26T17:00:00Z",
  "location": {
    "description": "Board room"
  }
}

Using Application Calendars with scheduling functions

You can check an Application Calendar’s availability the same way you would with standard Cronofy accounts:

{
  "participants": [
    {
      "members": [
        { "sub": "apc_64b17fbb8090ea21640c9152" },
        { "sub": "acc_5ba21743f408617d1269ea1e" }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2024-10-25T09:00:00Z",
      "end": "2024-10-25T18:00:00Z"
    },
    {
      "start": "2024-10-26T09:00:00Z",
      "end": "2024-10-26T18:00:00Z"
    }
  ]
}

Other Cronofy functionalities that are supported by Application Calendars include:

• Assigning Availability Rules and Available Periods.
• Using the Availability Query to drive Real-Time Scheduling links.
• Combining Cronofy’s calendar synchronisation and scheduling API with companion UI Elements.

Considerations

Because Application Calendars are hosted by Cronofy and do not have a mailbox, they are unable to send and receive invites to events. Instead, you can create the event within the Application Calendar and send a Smart Invite to any attendees, so that once accepted, the event is also created in the attendee’s calendar.