calendly（calendly 工具）

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:

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):

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:

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:

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:

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>:

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:

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

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

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:

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.