Step by Step Guide to Building a Cal.com API Integration in Python

Aug 16, 2024 • 5 minute read

Introduction

Hey there, fellow developer! Ready to supercharge your scheduling game with Cal.com's API? Let's dive into building a slick Python integration that'll have you managing bookings like a pro in no time.

Prerequisites

Before we jump in, make sure you've got:

A Python environment (3.7+ recommended)
The requests library (pip install requests)
A Cal.com API key (grab one from your Cal.com dashboard)

Setting Up the Project

Let's kick things off:

import requests
import json

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api.cal.com/v1'

Authentication

Cal.com uses API key authentication. Easy peasy:

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

Making API Requests

Time to get our hands dirty with some requests:

# GET request example
def get_event_types():
    response = requests.get(f'{BASE_URL}/event-types', headers=headers)
    return response.json()

# POST request example
def create_booking(event_type_id, start_time, end_time, name, email):
    payload = {
        'eventTypeId': event_type_id,
        'start': start_time,
        'end': end_time,
        'name': name,
        'email': email
    }
    response = requests.post(f'{BASE_URL}/bookings', headers=headers, json=payload)
    return response.json()

Handling Responses

Always be prepared for what the API throws back at you:

def handle_response(response):
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}")
        print(response.text)
        return None

Implementing Core Functionalities

Let's build out the meat of our integration:

def list_available_slots(event_type_id, date):
    response = requests.get(f'{BASE_URL}/availability/{event_type_id}?date={date}', headers=headers)
    return handle_response(response)

def update_booking(booking_id, updates):
    response = requests.patch(f'{BASE_URL}/bookings/{booking_id}', headers=headers, json=updates)
    return handle_response(response)

def cancel_booking(booking_id):
    response = requests.delete(f'{BASE_URL}/bookings/{booking_id}', headers=headers)
    return handle_response(response)

Webhooks (Optional)

If you're feeling fancy, set up a webhook to stay in the loop:

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event = request.json
    # Process the event
    print(f"Received event: {event['type']}")
    return '', 200

if __name__ == '__main__':
    app.run(port=5000)

Best Practices

Remember to:

Respect rate limits (check the API docs for specifics)
Keep your API key secret (use environment variables in production)
Implement proper error handling and logging

Testing the Integration

Don't forget to test! Here's a quick example:

import unittest

class TestCalIntegration(unittest.TestCase):
    def test_get_event_types(self):
        result = get_event_types()
        self.assertIsNotNone(result)
        self.assertIsInstance(result, list)

if __name__ == '__main__':
    unittest.main()

Conclusion

And there you have it! You've just built a solid Cal.com API integration in Python. With these building blocks, you can create powerful scheduling workflows tailored to your needs. Remember, the Cal.com API is your oyster – keep exploring and building awesome things!

Resources

Now go forth and schedule like a boss! Happy coding! 🚀