Schedule Events with AI Agents

Enable AI assistants or agents in your product to book meetings end‑to‑end via Calendly’s Scheduling API endpoint. This guide covers how to programmatically leverage collected booking details to create a scheduled event using the Create Event Invitee endpoint.

Use this pattern when you want automated booking inside a chat, workflow, or copilot experience without redirecting users to Calendly. This flow will require a securely stored admin user-type API Personal Access Token (PAT). Since no user intervention is involved, OAuth 2.0-based authentication won’t typically be used. Admin’s can access all organization data via webhooks.

How It Works

1. Determine the event type (and/or host) to book (agent maps user intent -> event type / host).

2. Select a timeslot (via GET /event_type_available_times)

3. Create the invitee with POST /invitees, including event_type, start_time (UTC), and invitee details.

4. Return confirmation: show booking summary plus optionally display reschedule and cancel links.

Key Endpoints

• GET /event_types OR GET /event_types/{uuid}
  Retrieve the entire organization or specific user’s/owner’s event types to map intent -> event type.

• GET /event_type_available_times
  Retrieve the appropriate event type available times to allow invitee to choose from. 

• POST invitees
  Schedule a meeting by creating an invitee for a specific event/time.

*Base URL: https://api.calendly.com/{ENDPOINT}

Common Use Cases

• Conversational scheduling: After a short dialog, the agent proposes 2–3 times and books the selected slot.

• Triage -> schedule: Bot determines the right user/event type (Sales/Success/Recruiting) and books.

• Hands‑free follow‑ups: Agent books time and includes additional event guests as CCs.

Steps to Implement

The steps below assume you’ve configured your AI agent to collect the required and optional details to begin the scheduling flow. Considerations such as the reason for the meeting, their locale, preference on location, and duration can all be considered when finding an appropriate event type. 

1) Map Intent to Event Type

Use your own rules or metadata to pick the right event type (e.g., “30‑min Demo” vs. “Onboarding Call”). Retrieve your organization/users event types using the /event_types endpoint. 

2) Select an Available Timeslot

Pass the event type URI to retrieve a list of event type available times from the /event_type_available_times endpoint. Present availability to the end‑user and collect a chosen start time. Normalize to UTC with a trailing Z (e.g., 2025-10-02T18:30:00Z).

3) Create the Invitee (Book the Meeting)

Endpoint: POST https://api.calendly.com/invitees

Important Considerations: The Location Object representing the meeting location. This is required unless the Event Type does not specify a location, in which case it must be omitted. 

When included, it must contain location.kind. 

If the location.kind defined by the host could require invitee input (such as ask_invitee, outbound_call, or if multiple custom or physical locations exist), the invitee must provide the corresponding details in location.location.

Minimum request body:

Optional fields (popular):

• event_guests: array of additional email addresses to include on the event

• questions_and_answers: [ { "question": "Company", "answer": "Acme", "position": 1 } ]

• tracking: utm_source, utm_campaign, utm_medium, utm_content, utm_term, salesforce_uuid

• invitee.text_reminder_number: E.164 phone for SMS reminders (when configured as a question on the event type)

cURL example:

Response highlights:

• event (scheduled event URI), status, timezone

• cancel_url, reschedule_url

• questions_and_answers, text_reminder_number

• Lifecycle: created_at, updated_at; reschedule metadata (rescheduled, old_invitee, new_invitee)

5) Show Confirmation + Management Links

Confirm the booking in the user’s local timezone and optionally provide Cancel/Reschedule actions powered by the returned URLs.

Example: Book a 30‑Minute Demo via Agent

1. User: “Book a 30‑minute demo with Taylor next week, afternoons only.”

2. Agent: Maps intent -> event type URI for “30‑minute demo” for the user Taylor.

3. Agent: Retrieve event type available times using the event type URI

4. Agent: Offers Wed/Thu 2:30–4:30pm slots; user picks Thu 3:00pm ET.

5. Backend: POST /invitees with the chosen UTC start time and invitee info.

6. UI: Shows success state with reschedule/cancel links.

7. Invitation and other respective text/email notifications fire based on configurations set in the event type settings.

General Limitations & Considerations

• Subscription Tier: Calendly customers are required to be on a paid plan in order to access or use applications calling the Scheduling API.

• Timeslot accuracy: start_time must correspond to a valid open slot at booking time.

• Location selection: The Location Object representing the meeting location. This is required unless the Event Type does not specify a location, in which case it must be omitted. 

When included, it must contain location.kind. 

If the location.kind defined by the host could require invitee input (such as ask_invitee, outbound_call, or if multiple custom or physical locations exist), the invitee must provide the corresponding details in location.location.

Make note of our documentation pages for location kind and location parameters based on the location option.

• Event_type_available_times 7-day limit: this endpoint can only retrieve 7 days of available times per request. You may poll this endpoint at different 7 day intervals.

• Timezone rules: Use IANA timezones (e.g., America/New_York) and convert display times accordingly.

• Validation: Validate emails; consider common typos; avoid booking without user confirmation.

Error Handling Cheatsheet

• Validation error (missing or invalid field)

  • Status - 400

  • Show actionable error; re‑collect inputs

• Unauthorized token

  • Status - 401

  • Refresh token or re‑authenticate

• Forbidden (policy or scope)

  • Status - 403

  • Route to human or request elevated permissions

• Not found (event type or time slot)

  • Status - 404

  • Re‑query availability and propose alternatives

• Transient server issue

  • Status - 5xx

  • Retry with backoff; show friendly fallback

QA / UAT Checklist

• Booking succeeds with minimal fields (name, email, timezone, UTC start_time)

• Returned reschedule/cancel links are visible and functional in your UI

• Timezone verified across confirmation methods (emails/UI)

• event_guests honored (when provided)

• tracking fields reach downstream reporting/CRM

• Logs redact PII; errors are user‑friendly and specific