Calendly API: Complete Developer Guide

The Calendly API lets you integrate scheduling functionality directly into your software. Whether you're connecting a CRM database, building automated reports, or just managing appointments in your app, the API gives you the tools you need. This guide covers how to use the Calendly API properly and where its limitations lie. We'll also look at why tools like Zeeg may be a better choice for developers.

What the Calendly API can do

The Calendly API is a REST interface that gives you access to scheduling data. With version 2 (the current version), you get access to:

• User data and organization info
• Event types and booking links
• Scheduled events and invitee data
• Availability times
• Real-time updates via webhooks

The API works with different authentication methods and integrates into most development environments.

Authentication: Getting access

Personal Access Token (simple)

For your own projects or internal tools:

1. Go to your Calendly settings
2. Click "API & Webhooks"
3. Create a new token
4. Use the token in your API calls

curl -H "Authorization: Bearer your_token_here" \
  https://api.calendly.com/users/me

OAuth 2.0 (for multi-user apps)

If other people will use your app:

1. Register your app with Calendly
2. Implement the OAuth flow
3. Exchange authorization codes for access tokens

OAuth is more complex but necessary for public applications.

Essential API endpoints

Getting user information

# Get your own info
GET /users/me

# All members of an organization
GET /organization_memberships?organization={org_uri}

Event types and booking links

# All event types for a user
GET /event_types?user={user_uri}

# All event types for an organization
GET /event_types?organization={org_uri}

Managing scheduled events

# List events
GET /scheduled_events

# Cancel an event
POST /scheduled_events/{event_uuid}/cancellation

Checking availability

# Available times for an event type
GET /event_type_available_times?event_type={uri}&start_time=2024-01-20T00:00:00Z

# User's busy times
GET /user_busy_times?user={user_uri}&start_time=2024-01-20T00:00:00Z

Webhooks: Getting real-time updates

Webhooks automatically send you notifications when things happen. This is useful for keeping your own systems up to date.

Setting up webhooks

POST /webhook_subscriptions
{
  "url": "https://your-app.com/webhook",
  "events": ["invitee.created", "invitee.canceled"],
  "organization": "{organization_uri}",
  "scope": "organization"
}

What happens when

• invitee.created: Someone books an appointment
• invitee.canceled: Appointment gets canceled
• Rescheduling: Sends both "canceled" and "created" events

Processing webhook data

app.post('/webhook', (req, res) => {
  const { event, payload } = req.body;
  
  switch(event) {
    case 'invitee.created':
      console.log('New appointment:', payload.event.name);
      // Save appointment to your database
      saveAppointment(payload);
      break;
      
    case 'invitee.canceled':
      console.log('Appointment canceled:', payload.event.name);
      // Mark appointment as canceled
      cancelAppointment(payload);
      break;
  }
  
  res.status(200).send('OK');
});

What the API CAN'T do

Here's where it gets frustrating. Like all good things, Calendly API also has some downsides:

Can't create events: You can't book appointments directly through the API. You have to use Calendly widgets for that.

Can't set availability: Working hours and available slots can only be set through the Calendly interface.

Can't create event types: New event types must be created manually in Calendly.

This makes the API mainly a "read-only" tool with limited write capabilities.

API v1 is going away - time for v2

‼️ Important: Calendly is deprecating API v1 starting August 2025. If you're still using v1, you need to migrate.

What v2 does better

• OAuth 2.0 instead of API keys
• More endpoints and features
• Better security
• Admin functions for organizations

Migration checklist

1. Check which API version you're using
2. Create new OAuth credentials or Personal Access Tokens
3. Test all your API calls with v2
4. Note: v2 is NOT compatible with v1 - data structures are different

Practical examples

Getting all booking links for a team

UTM parameters for tracking

You can append custom parameters to booking links:

https://calendly.com/your-link?utm_source=newsletter&utm_campaign=december

This data then appears in webhook payloads and helps with tracking.

Showing available times

GET /event_type_available_times?event_type={uri}&start_time=2024-01-20T00:00:00Z&end_time=2024-01-27T00:00:00Z

This lets you display free slots in your own app, even though the actual booking goes through Calendly.

Common problems and solutions

"I can't create events"

That's normal. Use Calendly widgets or inline embeds in your app instead.

"Webhooks aren't working"

Check:

• Do you have a paid plan? (Webhooks aren't available on the free plan)
• Is your webhook URL accessible?
• Are you returning HTTP 200?

"Rate limits reached"

Calendly doesn't document specific limits, but implement retry logic anyway and be conservative with requests.

Zeeg: A better alternative for developers

What Zeeg does better

• Complete API: You can create, modify, and delete events
• GDPR compliant: Data stays in Europe
• More flexibility: Create event types and set availability via API
• Simpler: Clearer documentation, better integration

Zeeg API example

// Create an event (not possible with Calendly!)
POST /api/v1/events
{
  "title": "Customer meeting",
  "start_time": "2024-01-20T14:00:00Z",
  "duration": 30,
  "attendees": ["customer@example.com"]
}

Pricing

• Starter: Free forever
• Professional: $10/month per user
• Business: $16/month per user

Much cheaper than Calendly and without API restrictions.

Conclusion

The Calendly API is okay for simple integrations but has frustrating limitations. You can read data and use webhooks, but real automation is difficult.

For companies that value data privacy and need more API control, Zeeg is the better choice. The API is more modern, flexible, and GDPR compliant.

If you're sticking with Calendly: Don't forget to migrate to v2 before August 2025!

Frequently asked questions (FAQ)

Is the Calendly API free?

Yes and no. You can access most Calendly API endpoints with a free Calendly account, including basic GET and POST requests. However, some features require paid plans:

• Webhooks need at least a Standard plan ($10/user/month)
• Enterprise-specific endpoints require Enterprise plans
• Advanced features like admin-level organization management need paid subscriptions

Is Calendly actually free?

Calendly offers a free plan with basic features, but it's quite limited:

• Only 1 event type
• Basic integrations only
• No webhooks
• Calendly branding on booking pages

For any serious business use, you'll likely need a paid plan starting at $10/user/month.

Is Calendly webhook free?

No, webhooks are not available on Calendly's free plan. You need at least:

• Standard plan ($10/user/month)
• Teams plan ($16/user/month)
• Enterprise plan (custom pricing)

This is one of the biggest limitations if you're building integrations that need real-time updates.

Can I integrate Calendly with my website?

Yes, there are several ways to integrate Calendly:

Embed options (easiest):

• Inline embed: Shows booking page directly on your site
• Popup widget: Opens booking in a modal
• Text/button widget: Floating button that opens popup

API integration (more control):

• Use scheduling URLs from the API
• Display available times in your interface
• Process booking data through webhooks

Example inline embed:

<div class="calendly-inline-widget" 
     data-url="https://calendly.com/your-link" 
     style="min-width:320px;height:630px;"></div>
<script type="text/javascript" 
        src="https://assets.calendly.com/assets/external/widget.js"></script>

The embed approach is much simpler than using the API directly, especially since you can't create bookings through the API anyway.