calendly

---
name: calendly
description: Calendly scheduling API. Use when user mentions "Calendly", "calendly.com", "schedule a meeting", "booking link", "event types", or asks about interview scheduling.
---

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name CALENDLY_TOKEN` or `zero doctor check-connector --url https://api.calendly.com/users/me --method GET`

## Core APIs

### Get Current User

Returns the authenticated user's URI and organization URI — needed for subsequent calls:

```bash
curl -s "https://api.calendly.com/users/me" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '{uri, name, email, organization: .current_organization}'
```

### List Event Types

List all event types for the current user. First get your user URI from the step above.

Replace `<user-uri>` with the full URI from `GET /users/me` (e.g., `https://api.calendly.com/users/AAAAAAA`):

```bash
curl -s "https://api.calendly.com/event_types?user=<user-uri>" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '[.collection[] | {uri, name, duration, active, scheduling_url}]'
```

### List Scheduled Events

List upcoming scheduled events for a user. Replace `<user-uri>` with your user URI:

```bash
curl -s "https://api.calendly.com/scheduled_events?user=<user-uri>&status=active&count=20" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '[.collection[] | {uri, name, status, start_time, end_time, location: .location.type}]'
```

### List Past Scheduled Events

Replace `<user-uri>` with your user URI:

```bash
curl -s "https://api.calendly.com/scheduled_events?user=<user-uri>&status=canceled&count=20" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '[.collection[] | {uri, name, status, start_time}]'
```

### Get a Scheduled Event

Replace `<event-uuid>` with the UUID portion from a scheduled event URI:

```bash
curl -s "https://api.calendly.com/scheduled_events/<event-uuid>" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '{uri, name, status, start_time, end_time, invitees_counter}'
```

### List Invitees for an Event

Get all invitees (attendees) for a specific scheduled event. Replace `<event-uuid>`:

```bash
curl -s "https://api.calendly.com/scheduled_events/<event-uuid>/invitees" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '[.collection[] | {uri, name, email, status, created_at}]'
```

### Create Webhook Subscription

Receive real-time notifications when events are booked or canceled. Replace `<organization-uri>` with your org URI from `GET /users/me`.

Write to `/tmp/calendly_request.json`:

```json
{
  "url": "https://your-server.com/webhooks/calendly",
  "events": ["invitee.created", "invitee.canceled"],
  "organization": "<organization-uri>",
  "scope": "organization"
}
```

```bash
curl -s -X POST "https://api.calendly.com/webhook_subscriptions" --header "Authorization: Bearer $CALENDLY_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendly_request.json | jq '{uri, callback_url: .resource.callback_url, events: .resource.events}'
```

### List Webhook Subscriptions

```bash
curl -s "https://api.calendly.com/webhook_subscriptions?organization=<organization-uri>&scope=organization" --header "Authorization: Bearer $CALENDLY_TOKEN" | jq '[.collection[] | {uri, callback_url, events, state}]'
```

### Delete Webhook Subscription

Replace `<webhook-uuid>` with the UUID from the webhook URI:

```bash
curl -s -X DELETE "https://api.calendly.com/webhook_subscriptions/<webhook-uuid>" --header "Authorization: Bearer $CALENDLY_TOKEN" -w "\nHTTP Status: %{http_code}\n"
```

## Guidelines

1. **URIs as identifiers**: Calendly uses full URIs (e.g., `https://api.calendly.com/users/XXXXX`) as identifiers — not bare IDs. Always use the full URI in filter parameters.
2. **Read-only API**: You cannot create bookings or force-schedule meetings via API. Direct users to a Calendly scheduling link (`scheduling_url` in event types) for self-booking.
3. **Webhooks require paid plan**: Webhook subscriptions are only available on Standard plan and above.
4. **Scope**: Use `user` scope for individual events; `organization` scope for team-wide data.
5. **Pagination**: Use `page_token` from `pagination.next_page_token` to fetch subsequent pages.
6. **Event status**: `active` = upcoming/confirmed; `canceled` = canceled events.