Skip to main content
Cal.com logo

​
Overview

Add Cal.com to any ModuleX agent or workflow. Scheduling and booking management via the Cal.com v2 REST API (api.cal.com/v2).
Categories: Scheduling & Events · Productivity & Collaboration · Scheduling · Calendar · Auth: API Key · Actions: 6

​
Authentication

​
API Key

Authenticate using your Cal.com v2 API key
1

Step 1

Sign in to Cal.com at https://app.cal.com
2

Step 2

Navigate to Settings > Developer > API Keys
3

Step 3

Create a new API key or copy an existing one
4

Step 4

Paste the API key below

​
Required Credentials

FieldDescriptionRequiredFormat
Cal.com API KeyYour Cal.com v2 API key from Settings > Developer > API KeysYescal_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Available Actions

​
Parameters

​
booking_type
string
required
Type of booking: booking, instant, or recurring
​
attendee_name
string
required
Full name of the attendee
​
attendee_time_zone
string
required
Time zone of the attendee, e.g. America/New_York
​
start
string
required
Booking start time in ISO 8601 UTC format, e.g. 2024-08-13T09:00:00Z
​
attendee_email
string
Email address of the attendee
​
attendee_phone_number
string
Phone number in international format, e.g. +919876543210
​
attendee_language
string
Language for the booking confirmation
​
event_type_id
integer
ID of the event type (alternative to slug-based identification)
​
event_type_slug
string
Slug of the event type (use with username or team_slug)
​
username
string
Username of the individual event owner
​
team_slug
string
Team slug for team event type identification
​
organization_slug
string
Organization slug for slug-based event type identification
​
end_time
string
Booking end time in ISO 8601 format
​
length_in_minutes
integer
Override the event type default duration in minutes
​
guests
array
Additional guest email addresses to invite
​
location
string
Meeting location type: attendeeAddress, attendeeDefined, attendeePhone, integration
​
location_address
string
Physical address if location is attendeeAddress
​
location_value
string
Location string if location is attendeeDefined
​
location_phone
string
Phone number if location is attendeePhone
​
location_integration
string
Video conferencing integration if location is integration
​
recurrence_count
integer
Number of occurrences for recurring booking type
​
metadata
object
Custom key-value metadata, e.g. {“source”: “website”}
​
booking_fields_responses
object
Responses to custom booking form fields keyed by field slug
​
allow_conflicts
boolean
Bypass availability checks and allow double-booking
​
allow_booking_out_of_bounds
boolean
Allow booking outside the event type scheduling window
​
email_verification_code
string
Required when event type has email verification enabled

​
Response

{
  "$defs": {
    "BookingItem": {
      "additionalProperties": false,
      "description": "A booking object returned by the Cal.com API.",
      "properties": {
        "uid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Uid"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Start"
        },
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "End"
        },
        "attendees": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Attendees",
          "type": "array"
        },
        "hosts": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Hosts",
          "type": "array"
        },
        "event_type_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Event Type Id"
        },
        "meeting_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Meeting Url"
        },
        "location": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Location"
        }
      },
      "title": "BookingItem",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "booking": {
      "anyOf": [
        {
          "$ref": "#/$defs/BookingItem"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateBookingOutput",
  "type": "object"
}

​
Parameters

​
booking_id
string
required
The UID of the booking to cancel
​
cancellation_reason
string
The reason for cancelling the booking
​
cancel_subsequent_bookings
boolean
Whether to cancel all subsequent occurrences of a recurring booking

​
Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    }
  },
  "required": [
    "success"
  ],
  "title": "DeleteBookingOutput",
  "type": "object"
}

​
Parameters

​
max_pages
integer
Maximum number of pages to fetch (1-500, default 50)
​
status
array
Filter by status: upcoming, recurring, past, cancelled, unconfirmed
​
after_start
string
Return bookings that start after this time (ISO 8601)
​
before_end
string
Return bookings that end before this time (ISO 8601)
​
after_created_at
string
Return bookings created after this time (ISO 8601)
​
before_created_at
string
Return bookings created before this time (ISO 8601)
​
attendee_email
string
Filter bookings by attendee email
​
attendee_name
string
Filter bookings by attendee name
​
booking_uid
string
Filter bookings by booking UID
​
event_type_id
integer
Filter bookings by event type ID
​
sort_start
string
Sort bookings by start time: asc or desc
​
sort_end
string
Sort bookings by end time: asc or desc
​
sort_created
string
Sort bookings by creation time: asc or desc

​
Response

{
  "$defs": {
    "BookingItem": {
      "additionalProperties": false,
      "description": "A booking object returned by the Cal.com API.",
      "properties": {
        "uid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Uid"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Start"
        },
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "End"
        },
        "attendees": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Attendees",
          "type": "array"
        },
        "hosts": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Hosts",
          "type": "array"
        },
        "event_type_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Event Type Id"
        },
        "meeting_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Meeting Url"
        },
        "location": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Location"
        }
      },
      "title": "BookingItem",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "bookings": {
      "items": {
        "$ref": "#/$defs/BookingItem"
      },
      "title": "Bookings",
      "type": "array"
    },
    "total": {
      "default": 0,
      "title": "Total",
      "type": "integer"
    }
  },
  "required": [
    "success"
  ],
  "title": "GetAllBookingsOutput",
  "type": "object"
}

​
Parameters

​
start
string
required
Start date/time in ISO 8601 format (UTC)
​
end
string
required
End date/time in ISO 8601 format (UTC)
​
event_type_id
integer
ID of the event type to get slots for
​
event_type_slug
string
Slug of the event type (requires username or team_slug)
​
username
string
Username of the individual event owner
​
usernames
array
List of at least 2 usernames for a dynamic event
​
team_slug
string
Slug of the team for team event type slot lookup
​
organization_slug
string
Organization slug for slug-based event type lookup
​
time_zone
string
The time zone for the slot lookup
​
duration
integer
Override the default slot duration in minutes
​
format
string
Response format: range (start and end) or time (start only)
​
booking_uid_to_reschedule
string
UID of the booking being rescheduled to exclude from busy calculations

​
Response

{
  "$defs": {
    "GetBookableSlot": {
      "additionalProperties": false,
      "description": "A single available time slot.",
      "properties": {
        "time": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Time"
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Start"
        },
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "End"
        }
      },
      "title": "GetBookableSlot",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "slots": {
      "additionalProperties": {
        "items": {
          "$ref": "#/$defs/GetBookableSlot"
        },
        "type": "array"
      },
      "title": "Slots",
      "type": "object"
    }
  },
  "required": [
    "success"
  ],
  "title": "GetBookableSlotsOutput",
  "type": "object"
}

​
Parameters

​
booking_id
string
required
The UID of the booking to retrieve

​
Response

{
  "$defs": {
    "BookingItem": {
      "additionalProperties": false,
      "description": "A booking object returned by the Cal.com API.",
      "properties": {
        "uid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Uid"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Start"
        },
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "End"
        },
        "attendees": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Attendees",
          "type": "array"
        },
        "hosts": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Hosts",
          "type": "array"
        },
        "event_type_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Event Type Id"
        },
        "meeting_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Meeting Url"
        },
        "location": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Location"
        }
      },
      "title": "BookingItem",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "booking": {
      "anyOf": [
        {
          "$ref": "#/$defs/BookingItem"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "GetBookingOutput",
  "type": "object"
}

​
Response

{
  "$defs": {
    "EventTypeOption": {
      "additionalProperties": false,
      "description": "An event type with its ID and title.",
      "properties": {
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Label"
        },
        "value": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        }
      },
      "title": "EventTypeOption",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "event_types": {
      "items": {
        "$ref": "#/$defs/EventTypeOption"
      },
      "title": "Event Types",
      "type": "array"
    }
  },
  "required": [
    "success"
  ],
  "title": "ListEventTypeIdOptionsOutput",
  "type": "object"
}

​
Limits & Quotas

  • Cal.com does not publicly document rate limits for the v2 API; enterprise plans may have higher thresholds.
  • The free tier has a limited number of event types and team members.
  • Error model: non-2xx responses and timeouts are caught and returned as success=False + error rather than raising.

Calendly

Google Calendar

Luma