Calendly Scheduling API for AI Agents: A Group-Meeting Integration Guide

Implement the documented flow, then run the group test

Calendly’s guide describes event-type booking through its Scheduling API. Follow that contract first. Then add one controlled hard-meeting fixture so you can see which participant and coordination responsibilities still belong to your application.

1. 1

   Normalize the agent’s meeting intent

   Collect organizer or host, meeting purpose, duration, date window, locale, preferred times, location preference, invitee name and email, and confirmation policy. For the hard-meeting test, also add required and optional participants, meeting time zone, booking deadline, permitted outreach channels, and a stable meeting request ID. Do not map vague prose directly to a calendar write.
   • Ask for clarification when duration, date window, host authority, or required people are missing.
   • Keep the original instruction and run the workflow from typed fields.
   • Use IANA time zones for participant policy and display.
2. 2

   Authenticate for the documented Calendly API path

   Calendly documents OAuth for public applications acting on behalf of Calendly users and personal access tokens for internal or organization use. Store the Calendly organization or user context beside the meeting request. Treat token expiration, insufficient subscription access, and organization-role limits as separate integration states.
   • Keep credentials out of model prompts and logs.
   • Bind the selected host or organization to the authorized account.
   • Request user confirmation before the agent performs a booking side effect.
3. 3

   Map intent to an event type and host

   Use GET /event_types or the event-type detail endpoint to identify the meeting template. The official guide puts intent-to-event-type mapping in your application. Persist the selected event type, owner or host, duration, location rules, and selection reason so the model cannot silently switch the meeting contract later.
   • Reject an event type that conflicts with the requested duration or location.
   • Make collective or other host rules visible to the operator when they affect availability.
   • A meeting revision re-runs mapping instead of mutating hidden assumptions.
4. 4

   Read current event-type availability

   Call GET /event_type_available_times for the selected event type and bounded window. Calendly’s guide notes a 31-day retrieval limit and requires a valid open slot at booking time. Store the retrieved slots, query time, selected event type, and freshness. Convert display into the user’s local zone while preserving UTC at the API boundary.
   • Never treat a failed availability request as an open calendar.
   • Re-query after a stale slot or a 404 at booking.
   • Keep the user’s chosen local time and the submitted UTC time linked.
5. 5

   Confirm the invitee details and selected slot

   Present two or three valid choices, collect the invitee’s selection, and confirm name, email, time zone, location input, and required question answers. The documented flow supports additional event guests as CCs. For a hard group meeting, do not confuse a guest address on the final event with verified pre-booking availability from that required person.
   • Validate email and location fields before the side effect.
   • Show the exact event type, host, start, end, and time zone before booking.
   • Bind confirmation to one meeting revision and one chosen slot.
6. 6

   Create the invitee and verify the Calendly result

   Call POST /invitees with the event type, UTC start time, invitee, time zone, and required location or question fields. Persist the returned scheduled-event reference, status, time zone, and management URLs. Do not report success until the response matches the requested event type, start, invitee, and host context.
   • Return the confirmation in the user’s local time.
   • Expose cancel and reschedule paths when policy permits them.
   • Redact personally identifiable information from logs as Calendly’s QA guidance recommends.
7. 7

   Add the hard group-meeting participant test

   Create a fixture with three required people and one optional observer across two companies. Put one required person on Google, one on Microsoft, and leave one unconnected. Ask whether the selected event type’s available times represent every required participant’s current evidence. If not, your application still needs connected free/busy adapters, conversational availability collection, reminders, quorum rules, and candidate-slot generation before it calls the booking endpoint.
   • Required attendance remains a hard rule.
   • Calendar connection is optional; unconnected people get an approved response path.
   • An ambiguous reply or required decline creates a visible meeting state.
8. 8

   Add retries, idempotency, consent, and observability

   Calendly’s guide distinguishes validation, authorization, forbidden, not-found, and transient server errors. Your meeting layer also needs a booking idempotency key, attempt record, safe retry budget, and reconciliation path after an uncertain response. Trace intent mapping, participant consent, availability sources, chosen slot, confirmation, booking call, returned event, and any recovery by meeting request ID.
   • A repeated command does not create a second booking or duplicate participant messages.
   • A transient failure retries with a bound; a stale slot triggers a fresh availability query.
   • External outreach and booking authority are explicit and revocable.
9. 9

   Score completion at the product boundary

   For event-type booking, verify the scheduled event, invitee, host, time, location, and management links. For hard group scheduling, also verify required and optional roles, every availability source, cross-company overlap, final attendee set, invitation dispatch, and recovery state. The agent should return confirmed or a bounded exception, not ‘I sent a link’ or ‘I tried to book.’
   • Every terminal state has evidence and a safe next action.
   • A human can approve, deny, pause, or reclaim sensitive work.
   • The completion metric matches the promise shown to the user.

Calendly booking flow versus group scheduling execution

Compare the documented product boundary, not old assumptions about what an API can or cannot do.