Calendly API: Scheduling Intelligence in Your AI Workflow

15,306 downloads, 8 stars. The Calendly skill by @byungkyu connects your AI agent to Calendly's scheduling data through the Maton OAuth gateway. Query scheduled events, pull invitee information, check availability, and manage webhooks — all with a single MATON_API_KEY, no Calendly OAuth setup required.

The Problem It Solves

Calendly is where a significant portion of meeting logistics happen in modern businesses — but its API has traditionally been manual-only territory. Building Calendly automation requires OAuth 2.0 setup, token management, and understanding Calendly's resource-based API design (users → event types → scheduled events → invitees).

For AI agents that need scheduling context — knowing when meetings are booked, who's attending, what the event type is — this complexity is a barrier. The Maton gateway eliminates it: connect your Calendly account once, use a bearer token for all subsequent calls.

How the Maton Pattern Works

byungkyu's entire API skills catalog (Calendly, ClickUp, Google Meet, WhatsApp Business, Stripe) follows one pattern:

Your Agent
    │
    ▼
gateway.maton.ai/calendly/{api-path}
    │  Bearer: MATON_API_KEY
    ▼
api.calendly.com/{api-path}
    │  OAuth token auto-injected
    ▼
Calendly API Response

The Maton gateway proxies calls to Calendly's native API and injects your connected account's OAuth token. Same pattern, different service.

Core Operations

Get Your User Profile

python <<'EOF'
import urllib.request, os, json
 
req = urllib.request.Request('https://gateway.maton.ai/calendly/users/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
user = json.load(urllib.request.urlopen(req))
resource = user.get('resource', {})
print(f"Name: {resource.get('name')}")
print(f"Email: {resource.get('email')}")
print(f"URI: {resource.get('uri')}")  # save this - needed for other queries
EOF

The uri field (e.g., https://api.calendly.com/users/abc123) is your user reference used in other API calls.

List Event Types

python <<'EOF'
import urllib.request, os, json
 
user_uri = "https://api.calendly.com/users/YOUR_USER_ID"
url = f'https://gateway.maton.ai/calendly/event_types?user={urllib.parse.quote(user_uri)}'
 
req = urllib.request.Request(url)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
events = json.load(urllib.request.urlopen(req))
for et in events.get('collection', []):
    print(f"Event Type: {et['name']}")
    print(f"  Duration: {et['duration']} min")
    print(f"  URL: {et['scheduling_url']}")
    print(f"  Active: {et['active']}")
EOF

Event types are the templates (e.g., "30-min intro call", "1-hour consultation"). Each has a scheduling URL and duration.

List Scheduled Events

python <<'EOF'
import urllib.request, os, json
from urllib.parse import urlencode, quote
 
user_uri = "https://api.calendly.com/users/YOUR_USER_ID"
params = urlencode({
    'user': user_uri,
    'status': 'active',          # 'active' or 'canceled'
    'count': 20,
    'sort': 'start_time:asc',
})
url = f'https://gateway.maton.ai/calendly/scheduled_events?{params}'
 
req = urllib.request.Request(url)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
result = json.load(urllib.request.urlopen(req))
for event in result.get('collection', []):
    print(f"[{event['status']}] {event['name']}")
    print(f"  Start: {event['start_time']}")
    print(f"  End: {event['end_time']}")
    print(f"  URI: {event['uri']}")
EOF

Get Invitees for an Event

python <<'EOF'
import urllib.request, os, json
 
event_uuid = "YOUR_EVENT_UUID"
req = urllib.request.Request(
    f'https://gateway.maton.ai/calendly/scheduled_events/{event_uuid}/invitees'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
result = json.load(urllib.request.urlopen(req))
for invitee in result.get('collection', []):
    print(f"Invitee: {invitee['name']} ({invitee['email']})")
    print(f"  Status: {invitee['status']}")
    print(f"  Timezone: {invitee['timezone']}")
    # Custom questions they answered during booking:
    for q in invitee.get('questions_and_answers', []):
        print(f"  Q: {q['question']} → A: {q['answer']}")
EOF

The invitee data includes any custom questions from your Calendly booking page — names, company, project details, anything you've configured. This is where the scheduling intelligence becomes valuable.

Manage Webhooks

For event-driven workflows — get notified immediately when someone books or cancels:

python <<'EOF'
import urllib.request, os, json
 
data = json.dumps({
    "url": "https://your-server.com/calendly-webhook",
    "events": ["invitee.created", "invitee.canceled"],
    "organization": "https://api.calendly.com/organizations/YOUR_ORG_ID",
    "user": "https://api.calendly.com/users/YOUR_USER_ID",
    "scope": "user"
}).encode()
 
req = urllib.request.Request(
    'https://gateway.maton.ai/calendly/webhook_subscriptions',
    data=data, method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
 
webhook = json.load(urllib.request.urlopen(req))
print(f"Webhook created: {webhook['resource']['uri']}")
EOF

Setup

clawhub install calendly-api

1. Create an account at maton.ai → get your API key
2. Go to ctrl.maton.ai → create Calendly connection → authorize via OAuth
3. export MATON_API_KEY="your_maton_key"

Use Cases

Pre-meeting preparation automation. When a meeting is booked (invitee.created webhook), have Claude fetch the invitee's answers to your booking questions, pull their LinkedIn profile or company information, generate a briefing document, and add it to your meeting notes — all before the meeting happens.

CRM sync. When a call is booked, create a CRM deal or contact automatically — populate it with the invitee's name, email, company, and the event type. No manual data entry.

Follow-up sequences. After a meeting ends (detect via invitee.created event + duration), have Claude draft follow-up emails personalized to the invitee's booking answers and send them via your email skill.

Scheduling analytics. Pull all scheduled events for a period, aggregate by event type, calculate no-show rates, identify peak booking times — generate a scheduling intelligence report for sales or customer success teams.

Multi-tool coordination. When someone books a consultation, simultaneously create a ClickUp task for prep work, add a Notion entry, and generate a Google Meet link — coordinating all of byungkyu's API skills around a single scheduling event.

Practical Tips

Get your user URI first. Almost all Calendly API calls require your user URI as a query parameter. Run the /users/me query once, save the URI, and hardcode it into your agent scripts.

Custom questions are where the value is. If your booking pages have custom questions (company, budget, project type, how they heard about you), the invitee questions_and_answers field contains structured data that's directly useful for automation. Design your booking questions with automation in mind.

Webhooks beat polling for responsiveness. For workflows that need to react quickly to new bookings (sending confirmation emails, creating CRM entries), webhooks deliver the event immediately. Use polling for periodic reporting and analytics.

Event type URIs are stable. Unlike events (which are tied to specific time slots), event type URIs don't change when you edit the event template. Safe to cache.

Considerations

• Availability endpoint requires Calendly Pro. Checking a user's real-time availability requires a paid Calendly plan. Most scheduling data (events, invitees, types) is available on all plans.
• Pagination for large event sets. The API returns paginated results with a default of 20 per page. For historical reporting, implement pagination using the next_page_token from the response.
• Timezone handling. Calendly returns all times in ISO 8601 with UTC offsets. Build your time comparisons accordingly — especially important for multi-timezone team scheduling.
• Very low install count (4) vs high downloads. Same pattern as other byungkyu skills — the Maton account + OAuth connection step is a friction point. Once completed, the skill works reliably.

Why Calendly Specifically (Not Google Calendar)

There's an important architectural difference worth understanding. Google Calendar is a personal calendar — you query free/busy blocks, calculate intersections, and create events manually. Calendly is a scheduling marketplace: event types represent service packages, the availability API handles all the business logic, and there's an official Scheduling API designed specifically for AI agents that enables conversational booking without redirects or UI.

The conversational pattern it enables:

Agent: "I have Tuesday at 2pm or Wednesday at 3pm available."
User: "Wednesday at 3pm"
Agent: [POST /event_invitees] → "Confirmed! Calendar invite sent."

Calendly handles the availability calculation. The agent just presents options and books the selection. Thoughtly, a voice AI company, uses this pattern for phone scheduling — their agents book meetings within 90 seconds of a call starting, with zero drop-off. That's what a scheduling API purpose-built for AI looks like in production.

The Bigger Picture

Calendly represents an underappreciated data source for AI agents: intent and context, captured at the moment someone decides to meet with you. The booking page answers, the event type, the timing — all of this is information about what the person wants and who they are.

Most companies treat Calendly as a scheduling tool and nothing more. The Calendly API skill turns it into a signal source: the moment a meeting is booked, Claude can enrich it with external data, create downstream records, and set up pre-meeting workflows without any manual work.

Combined with byungkyu's ClickUp (task tracking), Google Meet (video conference creation), and WhatsApp Business (messaging) skills, the Calendly skill completes a full meeting lifecycle automation: booked → prepared → conducted → followed up.

View the skill on ClawHub: calendly-api