New Integration: Calendly

Description

Add Calendly integration to sync scheduled events, event types, invitees, and routing forms into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/google-calendar/ - Similar calendar/scheduling system
• integrations/cal_com/ - Meeting scheduling integration
• integrations/hubspot/ - For OAuth 2.0 reference

Required Files Structure

integrations/calendly/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Calendly API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Calendly API Integration

OAuth Setup

• Use OAuth 2.0 Authorization Code flow
• Authorization URL: https://auth.calendly.com/oauth/authorize
• Token URL: https://auth.calendly.com/oauth/token
• Required scopes:
  • Calendly API v2 does not use granular OAuth scopes; access is granted at the user or organization level based on the token owner's role

Key Endpoints

• GET /users/me - Get current user info
• GET /event_types?user={user_uri} - List event types for a user
• GET /event_types?organization={org_uri} - List event types for an organization
• GET /scheduled_events?user={user_uri} - List scheduled events
• GET /scheduled_events/{event_uuid} - Get a specific event
• GET /scheduled_events/{event_uuid}/invitees - List invitees for an event
• POST /scheduled_events/{event_uuid}/cancellation - Cancel an event
• GET /organization_memberships?organization={org_uri} - List organization members
• POST /webhook_subscriptions - Create a webhook subscription
• GET /webhook_subscriptions - List webhook subscriptions
• DELETE /webhook_subscriptions/{webhook_uuid} - Delete a webhook subscription
• GET /routing_forms?organization={org_uri} - List routing forms
• GET /routing_forms/{form_uuid}/submissions - List routing form submissions

Base URL: https://api.calendly.com

Events to Track

1. Scheduled Events

   • Event created / scheduled
   • Event canceled
   • Event rescheduled

2. Invitees

   • Invitee created (new booking)
   • Invitee canceled

3. Routing Forms

   • Routing form submission created

4. Event Types

   • Event type created / updated

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 Authorization Code flow in account-create.ts
• Create Calendly API utilities in utils.ts (handle pagination with next_token)
• Implement sync logic in schedule.ts for scheduled events, invitees, and event types
• Convert Calendly events to CORE activity format
• Add webhook support for real-time invitee.created and invitee.canceled events
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

MCP Tools to create

• CALENDLY_CANCEL_SCHEDULED_EVENT

  Tool to cancel a scheduled Calendly event by creating a cancellation record. Use when you need to permanently cancel an existing, active event. The cancellation will trigger notifications to all invitees.

• CALENDLY_CREATE_EVENT_INVITEE

  DEPRECATED: Use CALENDLY_POST_INVITEE instead. Tool to programmatically schedule Calendly meetings without UI redirects. Use when you need to book a meeting on behalf of an invitee via API. Requires a paid Calendly plan.

• CALENDLY_CREATE_EVENT_TYPE

  Tool to create a new one-on-one event type (kind: solo) in Calendly. Use when you need to programmatically create a new event type for scheduling meetings.

• CALENDLY_CREATE_ONE_OFF_EVENT_TYPE

  Creates a temporary Calendly one-off event type for unique meetings outside regular availability, requiring valid host/co-host URIs, a future date/range for date_setting, and a positive duration.

• CALENDLY_CREATE_SCHEDULING_LINK

  Create a single-use scheduling link. Creates a scheduling link that can be used to book an event. The link allows invitees to schedule up to the specified maximum number of events. Once the limit is reached, the link becomes inactive.

• CALENDLY_CREATE_SHARE

  Creates a customizable, one-time share link for a Calendly event type, allowing specific overrides to its settings (e.g., duration, availability, location) without altering the original event type.

• CALENDLY_CREATE_SINGLE_USE_SCHEDULING_LINK

  Creates a one-time, single-use scheduling link for an active Calendly event type, expiring after one booking.

• CALENDLY_CREATE_WEBHOOKS

  Tool to create a webhook subscription for receiving Calendly event notifications. Use when you need to set up automated notifications for events like meeting bookings or cancellations. Organization scope triggers webhooks for all events organization-wide, while user/group scopes limit triggering to specific users or groups.

• CALENDLY_DELETE_INVITEE_DATA

  Permanently removes all invitee data associated with the provided emails from past organization events, for data privacy compliance (requires Enterprise subscription; deletion may take up to one week).

• CALENDLY_DELETE_INVITEE_NO_SHOW

  Deletes an Invitee No-Show record by its uuid to reverse an invitee's 'no-show' status; the uuid must refer to an existing record.

• CALENDLY_DELETE_ORGANIZATION_MEMBERSHIP

  Tool to remove a user from a Calendly organization by membership UUID. Use when you need to revoke a user's access to an organization. Requires admin rights; organization owners cannot be removed.

• CALENDLY_DELETE_SCHEDULED_EVENT_DATA

  For Enterprise users, initiates deletion of an organization's scheduled event data between a start_time and end_time (inclusive, where start_time must be <= end_time); actual data deletion may take up to 7 days to complete.

• CALENDLY_DELETE_WEBHOOK_SUBSCRIPTION

  Deletes an existing webhook subscription to stop Calendly sending event notifications to its registered callback URL; this operation is idempotent.

• CALENDLY_GET_CURRENT_USER

  DEPRECATED: Use CALENDLY_GET_USER instead. Retrieves detailed information about the currently authenticated Calendly user.

• CALENDLY_GET_EVENT

  Use to retrieve a specific Calendly scheduled event by its UUID, provided the event exists in the user's Calendly account.

• CALENDLY_GET_EVENT_INVITEE

  Retrieves detailed information about a specific invitee of a scheduled event, using their unique UUIDs.

• CALENDLY_GET_EVENT_TYPE

  Retrieves details for a specific Calendly event type, identified by its UUID, which must be valid and correspond to an existing event type.

• CALENDLY_GET_EVENT_TYPE_AVAILABILITY

  Tool to retrieve availability schedules configured for a specific Calendly event type. Use when you need to get the availability rules including day-of-week schedules and date-specific overrides.

• CALENDLY_GET_GROUP

  Retrieves all attributes of a specific Calendly group by its UUID; the group must exist.

• CALENDLY_GET_GROUP_RELATIONSHIP

  Retrieves a specific Calendly group relationship by its valid and existing UUID, providing details on user-group associations and membership.

• CALENDLY_GET_INVITEE_NO_SHOW

  Retrieves details for a specific Invitee No Show record by its UUID; an Invitee No Show is marked when an invitee does not attend a scheduled event.

• CALENDLY_GET_ORGANIZATION

  Tool to retrieve information about a specific Calendly organization. Use when you need to get organization details such as name, slug, or timestamps.

• CALENDLY_GET_ORGANIZATION_INVITATION

  Retrieves a specific Calendly organization invitation using its UUID and the parent organization's UUID.

• CALENDLY_GET_ORGANIZATION_MEMBERSHIP

  Retrieves a specific Calendly organization membership by its UUID, returning all its attributes.

• CALENDLY_GET_ROUTING_FORM

  Retrieves a specific routing form by its UUID, providing its configuration details including questions and routing logic.

• CALENDLY_GET_ROUTING_FORM_SUBMISSION

  Tool to retrieve details about a specific routing form submission by its UUID. Use when you need submission details including questions, answers, and routing results.

• CALENDLY_GET_SAMPLE_WEBHOOK_DATA

  Tool to retrieve sample webhook payload data for testing webhook subscriptions. Use when you need to verify webhook setup and understand the data structure before creating actual webhook subscriptions.

• CALENDLY_GET_USER

  Retrieves comprehensive details for an existing Calendly user.

• CALENDLY_GET_USER_AVAILABILITY_SCHEDULE

  Retrieves an existing user availability schedule by its UUID; this schedule defines the user's default hours of availability.

• CALENDLY_GET_WEBHOOK_SUBSCRIPTION

  Retrieves the details of an existing webhook subscription, identified by its UUID, including its callback URL, subscribed events, scope, and state.

• CALENDLY_INVITEE_NO_SHOW

  Tool to mark an invitee as a no-show for a scheduled event. Use when an invitee fails to attend their scheduled meeting and you need to record their absence in Calendly.

• CALENDLY_LIST_ACTIVITY_LOG_ENTRIES

  Retrieves a list of activity log entries for a specified Calendly organization (requires an active Enterprise subscription), supporting filtering, sorting, and pagination.

• CALENDLY_LIST_EVENT_INVITEES

  Retrieves a list of invitees for a specified Calendly event UUID, with options to filter by status or email, and sort by creation time.

• CALENDLY_LIST_EVENT_TYPE_AVAILABLE_TIMES

  Fetches available time slots for a Calendly event type within a specified time range; results are not paginated.

• CALENDLY_LIST_EVENT_TYPE_MEMBERSHIPS

  Tool to retrieve a list of event type hosts (memberships) for a specific event type. Use when you need to see which users are configured as hosts for an event type.

• CALENDLY_LIST_EVENT_TYPES

  Tool to list all Event Types associated with a specified User or Organization. Use when you need to retrieve event types for a user or organization. Use scheduling_url from results directly; do not manually construct event type URLs.

• CALENDLY_LIST_EVENTS

  DEPRECATED: Use CALENDLY_LIST_SCHEDULED_EVENTS instead. Retrieves a list of scheduled Calendly events. Exactly one of user, organization, or group must be provided to scope the query. The invitee_email parameter is a filter and cannot be used as a scope. Admin rights may be needed when filtering by organization or group.

• CALENDLY_LIST_GROUP_RELATIONSHIPS

  Retrieves a list of group relationships defining an owner's role (e.g., member, admin) within a group; an owner can have one membership per group but multiple admin roles across different groups.

• CALENDLY_LIST_GROUPS

  Returns a list of groups for a specified Calendly organization URI, supporting pagination.

• CALENDLY_LIST_ORGANIZATION_INVITATIONS

  Retrieves a list of invitations for a specific organization, identified by its UUID.

• CALENDLY_LIST_ORGANIZATION_MEMBERSHIPS

  Retrieves a list of organization memberships.

• CALENDLY_LIST_OUTGOING_COMMUNICATIONS

  Retrieves a list of outgoing SMS communications for a specified organization; requires an Enterprise subscription and if filtering by creation date, both min_created_at and max_created_at must be provided to form a valid range.

• CALENDLY_LIST_ROUTING_FORMS

  Retrieves routing forms for a specified organization; routing forms are questionnaires used to direct invitees to appropriate booking pages or external URLs.

• CALENDLY_LIST_SCHEDULED_EVENTS

  Tool to retrieve a list of scheduled Calendly events. Use when you need to view events for a specific user, organization, or group. Requires exactly one of user, organization, or group parameter to scope the query.

• CALENDLY_LIST_USER_AVAILABILITY_SCHEDULES

  Retrieves all availability schedules for the specified Calendly user.

• CALENDLY_LIST_USER_BUSY_TIMES

  Fetches a user's busy time intervals (internal and external calendar events) in ascending order for a period up to 7 days; keyset pagination is not supported.

• CALENDLY_LIST_USER_LOCATIONS

  Tool to retrieve configured meeting location information for a given Calendly user. Use when you need to see all available location options configured by a user for their meetings.

• CALENDLY_LIST_USER_S_EVENT_TYPES

  DEPRECATED: Use CALENDLY_LIST_EVENT_TYPES instead. Retrieves event types for a user or organization; requires either the user or organization URI.

• CALENDLY_LIST_WEBHOOK_SUBSCRIPTIONS

  Retrieves webhook subscriptions for a Calendly organization; scope determines if user or group URI is also required for filtering.

• CALENDLY_ORGANIZATION_INVITATION

  Tool to invite a user to a Calendly organization via email. Use when you need to send an organization invitation to a new user. Requires organization owner or admin privileges.

• CALENDLY_POST_INVITEE

  Tool to create a new Event Invitee with standard notifications, calendar invites, reschedules, and workflows. Use when programmatically scheduling meetings via API. Requires paid Calendly plan (Standard+).

• CALENDLY_REMOVE_USER_FROM_ORGANIZATION

  Removes a user (who is not an owner) from an organization by their membership UUID, requiring administrative privileges.

• CALENDLY_REVOKE_USER_S_ORGANIZATION_INVITATION

  Revokes a pending and revokable (not yet accepted or expired) organization invitation using its UUID and the organization's UUID, rendering the invitation link invalid.

• CALENDLY_UPDATE_EVENT_TYPE

  Tool to update an existing one-on-one event type (kind: solo) in Calendly. Use when you need to modify event type settings such as name, duration, location, or description. NOTE: Currently only supports one-on-one event types.

• CALENDLY_UPDATE_EVENT_TYPE_AVAILABILITY

  Tool to update an event type availability schedule in Calendly. Use when you need to change the timezone or availability rules for an event type. WARNING: Updating rules will overwrite all existing rules - retrieve existing rules first using GET /event_type_availability_schedules.

Technical Notes

• Calendly API v2 uses URI-based resource identification (e.g., https://api.calendly.com/users/{uuid})
• Pagination uses page_token / next_page_token pattern
• Webhook events include: invitee.created, invitee.canceled, routing_form_submission.created
• Rate limits apply; implement exponential backoff
• All timestamps are in UTC ISO 8601 format
• Filter scheduled events by min_start_time and max_start_time

Resources

• Calendly API Documentation
• Getting Started with Calendly API
• OAuth Authentication Guide
• Webhook Subscriptions Guide
• API Reference (Stoplight)

Labels

enhancement, good first issue, integration, new-feature, new-integration