Calendars API Reference

Detailed documentation for calendar integration endpoints in the Cal.diy API v2.

Endpoints Overview

List Connected Calendars

GET /v2/calendars

Response

{
  "status": "success",
  "data": {
    "connectedCalendars": [
      {
        "integration": {
          "type": "google_calendar",
          "title": "Google Calendar",
          "slug": "google-calendar"
        },
        "credentialId": 123,
        "primary": {
          "externalId": "primary",
          "name": "john@gmail.com",
          "email": "john@gmail.com",
          "isSelected": true,
          "readOnly": false
        },
        "calendars": [
          {
            "externalId": "primary",
            "name": "john@gmail.com",
            "email": "john@gmail.com",
            "isSelected": true,
            "readOnly": false
          },
          {
            "externalId": "calendar-id-2",
            "name": "Work Calendar",
            "email": "john@gmail.com",
            "isSelected": true,
            "readOnly": false
          }
        ]
      }
    ],
    "destinationCalendar": {
      "id": 1,
      "integration": "google_calendar",
      "externalId": "primary",
      "name": "john@gmail.com"
    }
  }
}

Get Busy Times

Check busy times from connected calendars to understand availability.

GET /v2/calendars/busy-times

Query Parameters

Example Request

GET /v2/calendars/busy-times?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&loggedInUsersTz=America/New_York

Response

{
  "status": "success",
  "data": [
    {
      "start": "2024-01-15T10:00:00.000Z",
      "end": "2024-01-15T11:00:00.000Z",
      "title": "Team Meeting",
      "source": "google_calendar"
    },
    {
      "start": "2024-01-16T14:00:00.000Z",
      "end": "2024-01-16T15:00:00.000Z",
      "title": "Client Call",
      "source": "google_calendar"
    }
  ]
}

Calendar Connection

Check Calendar Connection

GET /v2/calendars/{calendar}/check

Path Parameters

Connect a Calendar

POST /v2/calendars/{calendar}/connect

This initiates the OAuth flow for calendar connection.

Disconnect a Calendar

DELETE /v2/calendars/{calendar}/disconnect

Supported Calendar Types

Destination Calendars

The destination calendar is where new bookings are created.

List Destination Calendars

GET /v2/destination-calendars

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "integration": "google_calendar",
      "externalId": "primary",
      "name": "john@gmail.com",
      "userId": 123,
      "eventTypeId": null,
      "credentialId": 456
    }
  ]
}

Selected Calendars

Selected calendars are checked for conflicts when calculating availability.

List Selected Calendars

GET /v2/selected-calendars

Response

{
  "status": "success",
  "data": [
    {
      "integration": "google_calendar",
      "externalId": "primary",
      "credentialId": 123
    },
    {
      "integration": "google_calendar",
      "externalId": "work-calendar-id",
      "credentialId": 123
    }
  ]
}

ICS Feed

Check ICS Feed

GET /v2/calendars/ics-feed/check

Save ICS Feed

POST /v2/calendars/ics-feed/save

{
  "url": "https://calendar.example.com/feed.ics"
}

Calendar Events

Get Calendar Event

GET /v2/calendars/{calendar}/events/{eventUid}

Response

{
  "status": "success",
  "data": {
    "id": "event-id-123",
    "title": "Meeting",
    "description": "Discussion",
    "start": {
      "time": "2024-01-15T10:00:00.000Z",
      "timeZone": "America/New_York"
    },
    "end": {
      "time": "2024-01-15T11:00:00.000Z",
      "timeZone": "America/New_York"
    },
    "attendees": [
      {
        "email": "attendee@example.com",
        "name": "Attendee Name",
        "responseStatus": "accepted"
      }
    ],
    "status": "accepted",
    "source": "google"
  }
}

Understanding Calendar Integration

How Calendars Affect Availability

1. Selected Calendars: Events from selected calendars block availability
2. Destination Calendar: New bookings are created in this calendar
3. Busy Times: The API aggregates busy times from all selected calendars

Calendar Sync Flow

1. User connects calendar (OAuth)
   POST /v2/calendars/google-calendar/connect

2. User selects which calendars to check for conflicts
   (Done via Cal.diy dashboard)

3. User sets destination calendar for new bookings
   (Done via Cal.diy dashboard)

4. When checking slots:
   - API fetches busy times from all selected calendars
   - Busy times are excluded from available slots

5. When booking is created:
   - Event is created in destination calendar
   - Confirmation emails sent to attendees

Cal.diy Event Identification

Cal.diy events in external calendars can be identified by their iCalUID ending with @Cal.diy (e.g., 2GBXSdEixretciJfKVmYN8@Cal.diy).

Team Calendar Integration

For team-level calendar management:

Team Conferencing

GET /v2/organizations/{orgId}/teams/{teamId}/conferencing

Connect Team Calendar

POST /v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/connect

Best Practices

1. Check connection status: Verify calendar is connected before operations
2. Handle OAuth expiry: Calendar tokens may expire, handle re-authentication
3. Respect rate limits: Calendar APIs have their own rate limits
4. Cache busy times: Busy times don't change frequently, cache appropriately
5. Use webhooks: Subscribe to booking events instead of polling calendars