cotera
Logo

Calendly

Authentication Type: API Key (Personal Access Token) Description: Manage Calendly scheduling data including events, event types, invitees, and availability schedules. List upcoming meetings, check who booked, cancel events, and inspect availability windows.

Authentication

To authenticate with Calendly, you need a Personal Access Token:

  1. Log in to your Calendly account at calendly.com
  2. Navigate to Integrations & Apps > API & Webhooks
  3. Under Personal Access Tokens, click Generate New Token
  4. Give the token a descriptive name and copy it

You'll need to provide:

  • apiKey string: Your Calendly Personal Access Token

Note: The token inherits the permissions of the user who created it. Organization-level operations require an admin-level token. Treat your token like a password and never share it publicly.

Users

Get Current User

Get the current authenticated user's profile. This returns the user URI and organization URI that are required as parameters for most other Calendly operations. Call this first to get the URIs you need.

Operation Type: Query (Read)

Parameters:

None required.

Returns:

  • uri string: The Calendly user URI (use this as the userUri parameter in other calls)
  • name string: Full name of the user
  • email string: Email address
  • schedulingUrl string: Public URL for the user's scheduling page
  • timezone string: User's timezone (e.g., America/New_York)
  • currentOrganization string: URI of the current organization
  • slug string: User slug for URL construction
  • avatarUrl string (nullable): URL to user avatar image
  • createdAt string: When the account was created
  • updatedAt string: When the user was last updated

Example Usage:

{}

Event Types

List Event Types

List all event types (meeting types) for a user. Returns meeting names, durations, scheduling URLs, and active status. Use Get Current User first to get the user URI.

Operation Type: Query (Read)

Parameters:

  • userUri string (required): The user URI from Get Current User (e.g., https://api.calendly.com/users/ABCDEF)
  • active boolean (nullable): Filter by active status. If null, returns all event types.
  • count number (nullable): Number of results per page (default 20, max 100)
  • pageToken string (nullable): Token for pagination from the previous response

Returns:

  • eventTypes array of objects: List of event types
    • uri string: The event type URI
    • name string: Name of the event type (e.g., "30 Minute Meeting")
    • slug string: URL-friendly slug
    • active boolean: Whether the event type is currently active
    • type string: StandardEventType or AdhocEventType
    • color string: Color code for the event type
    • duration number: Duration in minutes
    • description string (nullable): Description of the event type
    • schedulingUrl string: Public URL for scheduling this event type
    • kind string: solo, group, or round_robin
    • createdAt string: When the event type was created
    • updatedAt string: When the event type was last updated
  • pagination object: Pagination info
    • count number: Number of results returned
    • nextPage string (nullable): URL for the next page
    • nextPageToken string (nullable): Token for the next page

Example Usage:

{
  "userUri": "https://api.calendly.com/users/ABCDEF123456",
  "active": true,
  "count": 20
}

Events

List Events

List scheduled events for a user with optional date range and status filters. Use Get Current User first to get the user URI.

Operation Type: Query (Read)

Parameters:

  • userUri string (required): The user URI from Get Current User
  • minStartTime string (nullable): Only return events starting on or after this time (ISO 8601 format, e.g., 2024-01-01T00:00:00Z)
  • maxStartTime string (nullable): Only return events starting before this time (ISO 8601 format)
  • status string (nullable): Filter by event status: active or canceled. If null, returns all.
  • count number (nullable): Number of results per page (default 20, max 100)
  • pageToken string (nullable): Token for pagination

Returns:

  • events array of objects: List of scheduled events
    • uri string: The event URI (use this to get details or list invitees)
    • name string: Name of the event
    • status string: Event status: active or canceled
    • startTime string: Event start time in ISO 8601 format
    • endTime string: Event end time in ISO 8601 format
    • eventType string: URI of the event type
    • location object (nullable): Meeting location details
      • type string: Location type (e.g., google_conference, zoom, custom)
      • location string (nullable): Physical location or custom text
      • joinUrl string (nullable): URL to join the meeting (for virtual meetings)
    • meetingNotesPlain string (nullable): Meeting notes in plain text
    • createdAt string: When the event was created
    • updatedAt string: When the event was last updated
  • pagination object: Pagination info

Example Usage:

{
  "userUri": "https://api.calendly.com/users/ABCDEF123456",
  "minStartTime": "2024-06-01T00:00:00Z",
  "maxStartTime": "2024-06-30T23:59:59Z",
  "status": "active"
}

Get Event

Get details of a specific scheduled event including location, invitee count, and cancellation info.

Operation Type: Query (Read)

Parameters:

  • eventUri string (required): The event URI from List Events (e.g., https://api.calendly.com/scheduled_events/ABCDEF)

Returns:

  • uri string: The event URI
  • name string: Name of the event
  • status string: Event status
  • startTime string: Start time in ISO 8601 format
  • endTime string: End time in ISO 8601 format
  • eventType string: URI of the event type
  • location object (nullable): Meeting location details
  • inviteesCounter object: Invitee count information
    • total number: Total number of invitees
    • active number: Number of active invitees
    • limit number: Maximum number of invitees
  • meetingNotesPlain string (nullable): Meeting notes
  • createdAt string: When the event was created
  • updatedAt string: When the event was last updated
  • cancellation object (nullable): Cancellation details
    • canceledBy string: Who canceled (host or invitee)
    • reason string (nullable): Reason for cancellation

Example Usage:

{
  "eventUri": "https://api.calendly.com/scheduled_events/ABCDEF123456"
}

Cancel Event

Cancel a scheduled Calendly event. Provide the event UUID and an optional cancellation reason.

Operation Type: Mutation (Write)

Parameters:

  • eventUuid string (required): The event UUID (the last segment of the event URI, e.g., the ABCDEF part of https://api.calendly.com/scheduled_events/ABCDEF)
  • reason string (nullable): Optional reason for cancellation

Returns:

  • success boolean: Whether the cancellation was successful
  • canceledBy string: Who canceled the event
  • reason string (nullable): Reason provided for cancellation

Example Usage:

{
  "eventUuid": "ABCDEF123456",
  "reason": "Rescheduling to next week"
}

List Event Invitees

List all invitees for a specific scheduled event. Returns invitee names, emails, status, and responses to custom booking questions.

Operation Type: Query (Read)

Parameters:

  • eventUuid string (required): The event UUID (last segment of the event URI)
  • status string (nullable): Filter by invitee status: active or canceled. If null, returns all.
  • count number (nullable): Number of results per page (default 20, max 100)
  • pageToken string (nullable): Token for pagination

Returns:

  • invitees array of objects: List of event invitees
    • uri string: The invitee URI
    • name string: Full name of the invitee
    • email string: Email address of the invitee
    • status string: Invitee status: active or canceled
    • timezone string (nullable): Timezone of the invitee
    • createdAt string: When the invitee was added
    • updatedAt string: When the invitee record was last updated
    • rescheduleUrl string: URL for the invitee to reschedule
    • cancelUrl string: URL for the invitee to cancel
    • questionsAndAnswers array of objects: Custom questions and answers from the booking form
      • question string: The question asked
      • answer string: The answer provided
      • position number: Position/order of the question
  • pagination object: Pagination info

Example Usage:

{
  "eventUuid": "ABCDEF123456",
  "status": "active"
}

Availability

List Availability Schedules

List availability schedules for a user, showing which days and time intervals they are available for meetings. Use Get Current User first to get the user URI.

Operation Type: Query (Read)

Parameters:

  • userUri string (required): The user URI from Get Current User

Returns:

  • schedules array of objects: List of availability schedules
    • uri string: The schedule URI
    • name string: Name of the availability schedule
    • default boolean: Whether this is the default schedule
    • timezone string: Timezone for the schedule (e.g., America/New_York)
    • rules array of objects: Availability rules
      • type string: Rule type: wday (weekly day) or date (specific date)
      • intervals array of objects: Available time intervals
        • from string: Start time in HH:MM format
        • to string: End time in HH:MM format
      • wday string (nullable): Day of week (monday, tuesday, etc.) for weekly rules
      • date string (nullable): Specific date in YYYY-MM-DD format for date-based rules

Example Usage:

{
  "userUri": "https://api.calendly.com/users/ABCDEF123456"
}

Common Use Cases

Meeting Management:

  • List all upcoming meetings for the week and export to a report
  • Cancel meetings programmatically with a reason
  • Track invitee details and booking form responses

Scheduling Insights:

  • Monitor event types to see which meeting formats are most popular
  • Analyze booking patterns to optimize availability windows
  • Track cancellation rates and reasons

Sales & CRM Integration:

  • Pull invitee data from scheduled meetings to enrich CRM records
  • Combine with Apollo or LinkedIn to research prospects before calls
  • Track meeting volume as a sales activity metric

Operations & Reporting:

  • Build meeting dashboards by pulling all events for a date range
  • Monitor team availability schedules
  • Automate meeting follow-ups based on invitee data