# Cal.com Docs: API v2 Reference ## API v2 Reference - [API v2 Reference / ORGANIZATIONS (164 pages)](https://cal.com/docs/_llms/api-v2-reference/organizations.txt): Documentation for API v2 Reference / ORGANIZATIONS. ### Getting Started - [Introduction to API v2](https://cal.com/docs/api-reference/v2/introduction.md): Introduction to Cal.com API v2 endpoints - [OAuth](https://cal.com/docs/api-reference/v2/oauth.md): Authorize apps with Cal.com accounts using OAuth - [Access Control](https://cal.com/docs/api-reference/v2/access-control.md): Roles, permissions, and OAuth scopes for organizations and teams API v2 endpoints - [Migrating from API v1 to v2](https://cal.com/docs/api-reference/v2/v1-v2-differences.md): Complete guide for migrating your Cal.com integration from v1 to v2 - [MCP server](https://cal.com/docs/mcp-server.md): Connect AI clients to Cal.com scheduling through the Model Context Protocol using the hosted server at mcp.cal.com or a local instance. - [User booking limits](https://cal.com/docs/api-reference/v2/user-booking-limits.md): Cap the total number of bookings a user can accept across all event types per day, week, month, or year. - [Calendar invite descriptions](https://cal.com/docs/api-reference/v2/calendar-invites.md): Configure host and guest descriptions in booking calendar invites. - [AI agents](https://cal.com/docs/agents.md): How AI agents can use the Cal.com API v2 to manage scheduling - [Cal.com agent quickstart](https://cal.com/docs/agent-quickstart.md): Connect an AI agent to Cal.com with hosted MCP OAuth or API v2 device authorization ### CORE #### Me - [Get my profile](https://cal.com/docs/api-reference/v2/me/get-my-profile.md): If accessed using an OAuth access token, the `PROFILE_READ` scope is required. - [Update my profile](https://cal.com/docs/api-reference/v2/me/update-my-profile.md): Updates the authenticated user's profile. Email changes require verification and the primary email stays unchanged until verification completes, unless the new email is already a verified secondary email or the user is platform-managed. If accessed using an OAuth access token, the `PROFILE_WRITE` sc… - [Get my booking limits](https://cal.com/docs/api-reference/v2/me/get-my-booking-limits.md): Returns the authenticated user's global booking limits. Unset bounds are returned as null. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_READ` scope is required. - [Update my booking limits](https://cal.com/docs/api-reference/v2/me/update-my-booking-limits.md): Partially updates the authenticated user's global booking limits. Only fields present in the request body are changed; omit a field to leave it untouched, or set it to null to remove that limit. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth acces… - [Clear my booking limits](https://cal.com/docs/api-reference/v2/me/clear-my-booking-limits.md): Removes all of the authenticated user's global booking limits. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required. #### Contacts - [List personal contacts](https://cal.com/docs/api-reference/v2/contacts/list-personal-contacts.md): Returns the authenticated user's personal contacts from their Contacts page, ordered by stored name (nulls last), email and id, with limit/cursor pagination. `tagIds` narrows the list to contacts carrying at least one of the tags. When pagination.hasMore is true, pass pagination.nextCursor as cursor… - [Add a personal contact](https://cal.com/docs/api-reference/v2/contacts/add-a-personal-contact.md): Adds a personal contact to the authenticated user's Contacts page by email, with an optional name. The email is checked for its format and mail server first, and a user holds at most 5,000 contacts. Adding an email already in the user's contacts changes nothing, not even its name. If accessed using… - [Update a personal contact](https://cal.com/docs/api-reference/v2/contacts/update-a-personal-contact.md): Updates one of the authenticated user's personal contacts, changing only the fields given in the body; a body with no fields changes nothing and returns the contact as it is. `name` is the only field today. A contact on Cal (`type: calUser`) shows the name from their Cal account and can't have its n… - [Remove a personal contact](https://cal.com/docs/api-reference/v2/contacts/remove-a-personal-contact.md): Removes one of the authenticated user's personal contacts, with its tags. It cannot be undone: adding the email again makes a new contact, without the old one's tags. A contact the user does not have is not found. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required. #### Bookings - [Create a booking](https://cal.com/docs/api-reference/v2/bookings/create-a-booking.md): POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except: If eventTypeId in the request body is id of a regular event, then regular booking is created. - [Get all bookings](https://cal.com/docs/api-reference/v2/bookings/get-all-bookings.md): Cursor-based pagination. Pass the `pagination.nextCursor` from the previous response as the `cursor` query parameter to fetch the next page. Omit `cursor` to fetch the first page. `pagination.hasMore` is `false` and `pagination.nextCursor` is `null` when you've reached the last page. - [Get a booking by seat UID](https://cal.com/docs/api-reference/v2/bookings/get-a-booking-by-seat-uid.md): Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and want to retrieve the full booking details. - [Get a booking](https://cal.com/docs/api-reference/v2/bookings/get-a-booking.md): `:bookingUid` can be - [Get all the recordings for the booking](https://cal.com/docs/api-reference/v2/bookings/get-all-the-recordings-for-the-booking.md): Fetches all the recordings for the booking `:bookingUid`. Requires authentication and proper authorization. Access is granted to the booking organizer and hosts, and to team or organization members whose role can view the booking and has the `booking.readRecordings` permission, which team and organi… - [Get Cal Video real time transcript download links for the booking](https://cal.com/docs/api-reference/v2/bookings/get-cal-video-real-time-transcript-download-links-for-the-booking.md): Fetches all the transcript download links for the booking `:bookingUid`. Requires authentication and proper authorization. Access is granted to the booking organizer and hosts, and to team or organization members whose role can view the booking and has the `booking.readRecordings` permission, which… - [Reschedule a booking](https://cal.com/docs/api-reference/v2/bookings/reschedule-a-booking.md): Reschedule a booking or seated booking. - [Request to reschedule a booking](https://cal.com/docs/api-reference/v2/bookings/request-to-reschedule-a-booking.md): Request to reschedule a booking. The booking will be cancelled and the attendee will receive an email with a link to reschedule. - [Cancel a booking](https://cal.com/docs/api-reference/v2/bookings/cancel-a-booking.md): :bookingUid can be :bookingUid of an usual booking, individual recurrence or recurring booking to cancel all recurrences. - [Mark a booking absence](https://cal.com/docs/api-reference/v2/bookings/mark-a-booking-absence.md): The provided authorization header refers to the owner of the booking. - [Reassign a booking](https://cal.com/docs/api-reference/v2/bookings/reassign-a-booking.md): Reassigns the host of a round robin or managed event type booking. The provided authorization header refers to the owner of the booking. - [Reassign a booking to a specific host](https://cal.com/docs/api-reference/v2/bookings/reassign-a-booking-to-a-specific-host.md): Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking. - [Confirm a booking](https://cal.com/docs/api-reference/v2/bookings/confirm-a-booking.md): The provided authorization header refers to the owner of the booking. - [Confirm booking seats](https://cal.com/docs/api-reference/v2/bookings/confirm-booking-seats.md): Confirm selected seats on a booking whose event type requires confirmation and has seats. The authorization header refers to a host who can update the booking. - [Decline booking seats](https://cal.com/docs/api-reference/v2/bookings/decline-booking-seats.md): Decline selected seats on a booking whose event type requires confirmation and has seats. The authorization header refers to a host who can update the booking. - [Decline a booking](https://cal.com/docs/api-reference/v2/bookings/decline-a-booking.md): The provided authorization header refers to the owner of the booking. - [Get 'Add to Calendar' links for a booking](https://cal.com/docs/api-reference/v2/bookings/get-add-to-calendar-links-for-a-booking.md): Retrieve calendar links for a booking that can be used to add the event to various calendar services. Returns links for Google Calendar, Microsoft Office, Microsoft Outlook, and a downloadable ICS file. - [Get booking references](https://cal.com/docs/api-reference/v2/bookings/get-booking-references.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get Video Meeting Sessions. Only supported for Cal Video](https://cal.com/docs/api-reference/v2/bookings/get-video-meeting-sessions-only-supported-for-cal-video.md): Requires authentication and proper authorization. Access is granted to the booking organizer and hosts, and to team or organization members whose role can view the booking and has the `booking.readRecordings` permission, which team and organization admins and owners have by default. - [Get the routing trace for a booking](https://cal.com/docs/api-reference/v2/bookings-routing-trace/get-the-routing-trace-for-a-booking.md): Retrieve the step-by-step routing trace for a booking identified by its UID. Shows how the booking was routed through routing forms, CRM lookups, and host selection logic. - [Update booking location for an existing booking](https://cal.com/docs/api-reference/v2/bookings/update-booking-location-for-an-existing-booking.md): Updates the booking location in Cal.com and updates the corresponding calendar event via the organizer's connected credentials. For integration locations (e.g. Zoom, Google Meet, Cal Video), the endpoint also provisions a conference link. Attendees and hosts are notified of the location change by em… ##### Attendees - [Get all attendees for a booking](https://cal.com/docs/api-reference/v2/bookings-attendees/get-all-attendees-for-a-booking.md): Retrieve all attendees for a specific booking by its UID. The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. - [Add an attendee to a booking](https://cal.com/docs/api-reference/v2/bookings-attendees/add-an-attendee-to-a-booking.md): Add a new attendee to an existing booking by its UID. - [Get a specific attendee for a booking](https://cal.com/docs/api-reference/v2/bookings-attendees/get-a-specific-attendee-for-a-booking.md): Retrieve a specific attendee by their ID for a booking identified by its UID. The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. ##### Guests - [Add guests to an existing booking](https://cal.com/docs/api-reference/v2/bookings-guests/add-guests-to-an-existing-booking.md): Add one or more guests to an existing booking. Maximum 10 guests per request, with a limit of 30 total guests per booking. **Rate Limiting:** This endpoint is rate limited to 5 requests per minute to prevent abuse. **Seated Events:** This endpoint does not support seated ev… ##### Email Verification - [Check if email verification is required](https://cal.com/docs/api-reference/v2/bookings--email-verification/check-if-email-verification-is-required.md): Checks whether email verification is required for the given email. Returns true if verification is needed. - [Send email verification code](https://cal.com/docs/api-reference/v2/bookings--email-verification/send-email-verification-code.md): Sends a one-time verification code to the specified email address. - [Verify email with code](https://cal.com/docs/api-reference/v2/bookings--email-verification/verify-email-with-code.md): Verifies an email address using the one-time code that was previously sent. #### Schedules - [Create a schedule](https://cal.com/docs/api-reference/v2/schedules/create-a-schedule.md): Create a schedule for the authenticated user. - [Get all schedules](https://cal.com/docs/api-reference/v2/schedules/get-all-schedules.md): Get all schedules of the authenticated user. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get default schedule](https://cal.com/docs/api-reference/v2/schedules/get-default-schedule.md): Get the default schedule of the authenticated user. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get a schedule](https://cal.com/docs/api-reference/v2/schedules/get-a-schedule.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Update a schedule](https://cal.com/docs/api-reference/v2/schedules/update-a-schedule.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Delete a schedule](https://cal.com/docs/api-reference/v2/schedules/delete-a-schedule.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. #### Slots - [Get available time slots for an event type](https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type.md): There are 4 ways to get available slots for event type of an individual user: - [Reserve a slot](https://cal.com/docs/api-reference/v2/slots/reserve-a-slot.md): Make a slot not available for others to book for a certain period of time. If you authenticate using oAuth credentials, api key or access token then you can also specify custom duration for how long the slot should be reserved for (defaults to 5 minutes). Please make sure to pass… - [Get reserved slot](https://cal.com/docs/api-reference/v2/slots/get-reserved-slot.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Update a reserved slot](https://cal.com/docs/api-reference/v2/slots/update-a-reserved-slot.md): If you specify a custom reservation duration, you must authenticate using oAuth credentials, api key or access token. - [Delete a reserved slot](https://cal.com/docs/api-reference/v2/slots/delete-a-reserved-slot.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. #### Out of Office - [Get all out-of-office entries for the authenticated user](https://cal.com/docs/api-reference/v2/out-of-office/get-all-out-of-office-entries-for-the-authenticated-user.md): If accessed using an OAuth access token, the `SCHEDULE_READ` scope is required. - [Create an out-of-office entry for the authenticated user](https://cal.com/docs/api-reference/v2/out-of-office/create-an-out-of-office-entry-for-the-authenticated-user.md): If accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required. - [Update an out-of-office entry for the authenticated user](https://cal.com/docs/api-reference/v2/out-of-office/update-an-out-of-office-entry-for-the-authenticated-user.md): If accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required. - [Delete an out-of-office entry for the authenticated user](https://cal.com/docs/api-reference/v2/out-of-office/delete-an-out-of-office-entry-for-the-authenticated-user.md): If accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required. #### Notifications - [Register an app push subscription](https://cal.com/docs/api-reference/v2/notifications/register-an-app-push-subscription.md) - [Remove an app push subscription](https://cal.com/docs/api-reference/v2/notifications/remove-an-app-push-subscription.md) - [Create a Slack push linking intent](https://cal.com/docs/api-reference/v2/notifications/create-a-slack-push-linking-intent.md) - [Remove a Slack push subscription](https://cal.com/docs/api-reference/v2/notifications/remove-a-slack-push-subscription.md) - [Create a Telegram push linking intent](https://cal.com/docs/api-reference/v2/notifications/create-a-telegram-push-linking-intent.md) - [Remove a Telegram push subscription](https://cal.com/docs/api-reference/v2/notifications/remove-a-telegram-push-subscription.md) - [Create an iMessage push linking intent](https://cal.com/docs/api-reference/v2/notifications/create-an-imessage-push-linking-intent.md) - [Remove an iMessage push subscription](https://cal.com/docs/api-reference/v2/notifications/remove-an-imessage-push-subscription.md) - [Get the agent notification channel selection](https://cal.com/docs/api-reference/v2/notifications/get-the-agent-notification-channel-selection.md) - [Enable or disable an agent notification channel](https://cal.com/docs/api-reference/v2/notifications/enable-or-disable-an-agent-notification-channel.md) #### Credits - [Check available credits](https://cal.com/docs/api-reference/v2/credits/check-available-credits.md): Check if the authenticated user (or their org/team) has available credits and return the current balance. Third-party OAuth tokens require the `CREDITS_READ` scope. - [Charge credits](https://cal.com/docs/api-reference/v2/credits/charge-credits.md): Charge up to 10,000 credits with a covering balance. Team and organization charges require manageBilling permission. References are scoped to the caller; replays return charged: false and duplicate: true. Third-party OAuth tokens require the `CREDITS_WRITE` scope. #### Insights - [Get booking limits usage](https://cal.com/docs/api-reference/v2/insights/get-booking-limits-usage.md): How much of each booking limit is used in the day, week, month and year containing `date` (default today), per user in scope. Counts come from the same queries booking-limit enforcement uses. Reports the user's global limit and, when `eventTypeId` is given, the event type's own limit; team booking l… - [Get average booking duration](https://cal.com/docs/api-reference/v2/insights/get-average-booking-duration.md): Get average booking duration for user, team, or organization insights. - [Get booking event trends](https://cal.com/docs/api-reference/v2/insights/get-booking-event-trends.md): Get booking trend stats for user, team, or organization insights. - [Get booking KPI stats](https://cal.com/docs/api-reference/v2/insights/get-booking-kpi-stats.md): Get booking KPI stats for user, team, or organization insights. - [Get booking member stats](https://cal.com/docs/api-reference/v2/insights/get-booking-member-stats.md): Get booking member stats for user, team, or organization insights. - [Get failed bookings by routing field](https://cal.com/docs/api-reference/v2/insights/get-failed-bookings-by-routing-field.md): Get failed booking counts grouped by routing form field for user, team, or organization insights. - [Get routing form field options](https://cal.com/docs/api-reference/v2/insights/get-routing-form-field-options.md): Get routing form fields and options for user, team, or organization insights. - [Get routing form response headers](https://cal.com/docs/api-reference/v2/insights/get-routing-form-response-headers.md): Get routing form response headers for user, team, or organization insights. - [Get routing form responses](https://cal.com/docs/api-reference/v2/insights/get-routing-form-responses.md): Get paginated routing form responses for user, team, or organization insights. - [Get routing forms by status](https://cal.com/docs/api-reference/v2/insights/get-routing-forms-by-status.md): Get routing form response counts by booking status for user, team, or organization insights. - [Get routed-to users per period](https://cal.com/docs/api-reference/v2/insights/get-routed-to-users-per-period.md): Get routed-to booking counts by user and period for user, team, or organization insights. #### Allowlists - [Get the Cal.com IP allowlists](https://cal.com/docs/api-reference/v2/allowlists/get-the-calcom-ip-allowlists.md): Returns the IPv4 ranges Cal.com sends traffic from and receives traffic on, keyed by service. Poll this endpoint instead of hard-coding addresses, because they can change. - [Get the Cal.com IP allowlist of one service](https://cal.com/docs/api-reference/v2/allowlists/get-the-calcom-ip-allowlist-of-one-service.md) #### Timezones - [Timezones](https://cal.com/docs/api-reference/v2/timezones.md): Let a user pick a timezone by searching for a city or a timezone name - [Get timezones](https://cal.com/docs/api-reference/v2/timezones/get-timezones.md): Returns the cities Cal.com knows a timezone for, as a `city` to show the user and the IANA `timezone` to store and to send back to Cal.com. Without `search` every city is returned, around 7000 of them. ### CALENDARS #### Calendars - [Save an ICS feed](https://cal.com/docs/api-reference/v2/calendars/save-an-ics-feed.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. - [Check an ICS feed](https://cal.com/docs/api-reference/v2/calendars/check-an-ics-feed.md): If accessed using an OAuth access token, the `APPS_READ` scope is required. - [Get busy times](https://cal.com/docs/api-reference/v2/calendars/get-busy-times.md): Get busy times from a calendar. Example request URL is `https://api.cal.com/v2/calendars/busy-times?timeZone=Europe%2FMadrid&dateFrom=2024-12-18&dateTo=2024-12-18&calendar=135,skrauciz%40gmail.com&calendar=200,bob%40gmail.com`. - [Get all calendars](https://cal.com/docs/api-reference/v2/calendars/get-all-calendars.md): If accessed using an OAuth access token, the `APPS_READ` scope is required. - [Get OAuth connect URL](https://cal.com/docs/api-reference/v2/calendars/get-oauth-connect-url.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. - [Save Google or Outlook calendar credentials](https://cal.com/docs/api-reference/v2/calendars/save-google-or-outlook-calendar-credentials.md) - [Save Apple calendar credentials](https://cal.com/docs/api-reference/v2/calendars/save-apple-calendar-credentials.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. - [Check a calendar connection](https://cal.com/docs/api-reference/v2/calendars/check-a-calendar-connection.md): If accessed using an OAuth access token, the `APPS_READ` scope is required. - [Disconnect a calendar](https://cal.com/docs/api-reference/v2/calendars/disconnect-a-calendar.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. #### Cal Unified Calendars - [Get meeting details from calendar](https://cal.com/docs/api-reference/v2/cal-unified-calendars/get-meeting-details-from-calendar.md): Returns detailed information about a meeting including attendance metrics. If accessed using an OAuth access token, the `APPS_READ` scope is required. - [Update meeting details in calendar](https://cal.com/docs/api-reference/v2/cal-unified-calendars/update-meeting-details-in-calendar.md): Updates event information in the specified calendar provider. If accessed using an OAuth access token, the `APPS_WRITE` scope is required. #### Selected Calendars - [Add a selected calendar](https://cal.com/docs/api-reference/v2/selected-calendars/add-a-selected-calendar.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. - [Delete a selected calendar](https://cal.com/docs/api-reference/v2/selected-calendars/delete-a-selected-calendar.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. #### Destination Calendars - [Update destination calendars](https://cal.com/docs/api-reference/v2/destination-calendars/update-destination-calendars.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. #### Conferencing - [Conferencing Apps](https://cal.com/docs/api-reference/v2/conferencing-apps.md): Connect Zoom, Microsoft Teams or Google Meet to a user or a team - [Connect your conferencing application](https://cal.com/docs/api-reference/v2/conferencing/connect-your-conferencing-application.md): Only `google-meet` can be connected this way, and only for a user who already has a valid Google Calendar connection. Zoom and Microsoft Teams require an OAuth handshake - start it with `GET /v2/conferencing/{app}/oauth/auth-url` instead. Walkthrough: https://cal.com/docs/api-reference/v2/conferenci… - [Get OAuth conferencing app auth URL](https://cal.com/docs/api-reference/v2/conferencing/get-oauth-conferencing-app-auth-url.md): Returns the URL to send the user to so they can authorize Zoom or Microsoft Teams. Redirect the user's browser to it - the provider then returns them to a callback already registered by Cal.com, which stores the credential against the owner of the access token that started the flow. `returnTo` and `… - [Conferencing app OAuth callback](https://cal.com/docs/api-reference/v2/conferencing/conferencing-app-oauth-callback.md) - [List your conferencing applications](https://cal.com/docs/api-reference/v2/conferencing/list-your-conferencing-applications.md): If accessed using an OAuth access token, the `APPS_READ` scope is required. - [Set your default conferencing application](https://cal.com/docs/api-reference/v2/conferencing/set-your-default-conferencing-application.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. - [Get your default conferencing application](https://cal.com/docs/api-reference/v2/conferencing/get-your-default-conferencing-application.md): If accessed using an OAuth access token, the `APPS_READ` scope is required. - [Disconnect your conferencing application](https://cal.com/docs/api-reference/v2/conferencing/disconnect-your-conferencing-application.md): If accessed using an OAuth access token, the `APPS_WRITE` scope is required. ### EVENT TYPES & AUTOMATION #### Links - [Get a link](https://cal.com/docs/api-reference/v2/links/get-a-link.md): Returns hidden booking fields only to callers who are allowed to view them. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. - [Delete a link](https://cal.com/docs/api-reference/v2/links/delete-a-link.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. #### Event Types - [Create an event type](https://cal.com/docs/api-reference/v2/event-types/create-an-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. - [List event types](https://cal.com/docs/api-reference/v2/event-types/list-event-types.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get an event type](https://cal.com/docs/api-reference/v2/event-types/get-an-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Update an event type](https://cal.com/docs/api-reference/v2/event-types/update-an-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Delete an event type](https://cal.com/docs/api-reference/v2/event-types/delete-an-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get event type history](https://cal.com/docs/api-reference/v2/event-types/get-event-type-history.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get scheduling configuration](https://cal.com/docs/api-reference/v2/event-types/get-scheduling-configuration.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [List CRM sync errors for an event type](https://cal.com/docs/api-reference/v2/event-types/list-crm-sync-errors-for-an-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get event-type calendar-invite templates](https://cal.com/docs/api-reference/v2/event-types/get-event-type-calendar-invite-templates.md): Returns host and guest invite-description settings resolved from the event type, organization default when the mode is `inherit`, then Cal.com's standard description. Access matches reading the event type; OAuth clients require `EVENT_TYPE_READ`. Custom templates are limited to 5,000 characters. Man… - [Update event-type calendar-invite templates](https://cal.com/docs/api-reference/v2/event-types/update-event-type-calendar-invite-templates.md): Updates host and/or guest settings without changing other event-type fields; omitted audiences remain unchanged. `inherit` uses the organization default, `standard` uses Cal.com's standard description, and `custom` uses a supplied template of at most 5,000 characters. HTML tags are stripped and Mark… ##### Booking Fields - [Get booking fields](https://cal.com/docs/api-reference/v2/event-types/get-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Replace booking fields](https://cal.com/docs/api-reference/v2/event-types/replace-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Add custom booking fields](https://cal.com/docs/api-reference/v2/event-types/add-custom-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Update booking fields](https://cal.com/docs/api-reference/v2/event-types/update-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Delete a custom booking field](https://cal.com/docs/api-reference/v2/event-types/delete-a-custom-booking-field.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. ##### Webhooks - [Create a webhook](https://cal.com/docs/api-reference/v2/event-types-webhooks/create-a-webhook.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. - [Get all webhooks](https://cal.com/docs/api-reference/v2/event-types-webhooks/get-all-webhooks.md): If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. - [Delete all webhooks](https://cal.com/docs/api-reference/v2/event-types-webhooks/delete-all-webhooks.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. - [Update a webhook](https://cal.com/docs/api-reference/v2/event-types-webhooks/update-a-webhook.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. - [Get a webhook](https://cal.com/docs/api-reference/v2/event-types-webhooks/get-a-webhook.md): If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. - [Delete a webhook](https://cal.com/docs/api-reference/v2/event-types-webhooks/delete-a-webhook.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. #### Team Event Types - [Get team event-type calendar-invite templates](https://cal.com/docs/api-reference/v2/team-event-types/get-team-event-type-calendar-invite-templates.md): Returns host and guest settings resolved from the event type, an organization default when available, then Cal.com's standard description. Access matches reading the team event type: the `eventType.readTeamEventTypes` PBAC permission, or team ADMIN/OWNER role when PBAC does not grant it. OAuth clien… - [Update team event-type calendar-invite templates](https://cal.com/docs/api-reference/v2/team-event-types/update-team-event-type-calendar-invite-templates.md): Updates one or both audiences without changing other event-type fields; omitted audiences remain unchanged. Access matches updating the team event type: the `eventType.update` PBAC permission, or team ADMIN/OWNER role when PBAC does not grant it. OAuth clients require `TEAM_EVENT_TYPE_WRITE`. Custom… #### Events - [List Events (cursor pagination)](https://cal.com/docs/api-reference/v2/events/list-events-cursor-pagination.md): Returns the Events the authenticated user hosts: Events they own, plus Events they have accepted a co-host invitation to. A co-hosted Event may be owned by a team, so a team-owned Event can appear here — but team-owned Events the user neither hosts nor co-hosts are not returned by this endpoint; lis… - [Create an Event](https://cal.com/docs/api-reference/v2/events/create-an-event.md): Creates a draft Event for the authenticated user. A draft is not public and nobody can register until it is published with `POST /v2/events/{uuid}/publish`. To create an Event owned by a team, use `POST /v2/teams/{teamId}/events`. - [Get an Event](https://cal.com/docs/api-reference/v2/events/get-an-event.md): Returns one Event by UUID. The authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. Events are fixed-… - [Update an Event](https://cal.com/docs/api-reference/v2/events/update-an-event.md): Updates the properties sent and leaves every other property as it is. Takes the same properties as `POST /v2/events` except `locations`, which have their own endpoints under `/v2/events/{uuid}/locations`. - [Publish an Event](https://cal.com/docs/api-reference/v2/events/publish-an-event.md): Takes a draft Event live: its public page becomes reachable, guests can RSVP, the occurrence lands on the hosts' calendars. Idempotent for an Event that is already published. A cancelled Event cannot be published. The authenticated user must be its owner, one of its hosts, or a member of the owning… - [Cancel an Event](https://cal.com/docs/api-reference/v2/events/cancel-an-event.md): Cancels a published Event and notifies every registered guest; paid registrations are refunded. The Event stays listed with `cancelledAt` set. Drafts cannot be cancelled (delete them instead) and neither can Events that already ended. The authenticated user must be its owner, one of its hosts, or a… - [Delete an Event](https://cal.com/docs/api-reference/v2/events/delete-an-event.md): Removes an Event, its registrations and its occurrence booking. An upcoming published Event is cancelled first, notifying its guests, and disappears from listings immediately; it is permanently removed once those notices have gone out. An Event cancelled more than seven days earlier is removed at on… - [Upload an Event cover image](https://cal.com/docs/api-reference/v2/events/upload-an-event-cover-image.md): Uploads a JPEG, PNG or WebP image of at most 10 MB as the Event's cover, replacing the current cover and any poster design. The response carries the image's public URL and its dimensions as displayed. - [Remove an Event cover image](https://cal.com/docs/api-reference/v2/events/remove-an-event-cover-image.md): Removes the Event's cover image and any poster design. Idempotent for an Event without a cover. - [Upload an Event person avatar](https://cal.com/docs/api-reference/v2/events/upload-an-event-person-avatar.md): Uploads a photo for a person in the Event's lineup or schedule and returns its public URL, which you then set as that person's `avatarUrl` when updating the Event. Uploading alone does not change the Event. - [List an Event's bookings](https://cal.com/docs/api-reference/v2/events/list-an-events-bookings.md): Returns the Event's guests in the statuses given by `status`, confirmed guests by default. A confirmed guest holds a seat on the Event's occurrence booking, the same way `GET /v2/bookings` reads attendees; pass `status=PENDING_APPROVAL` to list the guests waiting for approval, `WAITLISTED` for the w… - [Count an Event's guests](https://cal.com/docs/api-reference/v2/events/count-an-events-guests.md): Returns how many of the Event's guests are in each status, how many answered each RSVP, how many are checked in and how many seats each location holds, as the roster's tabs show them. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning t… - [Check in a guest by registration id](https://cal.com/docs/api-reference/v2/events/check-in-a-guest-by-registration-id.md): Records a door check-in for one registration, the roster's manual tap (no QR involved). Same access as approving/declining guests — an external co-host may also work the door. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is requ… - [Undo a guest's check-in](https://cal.com/docs/api-reference/v2/events/undo-a-guests-check-in.md): Clears a mistaken door check-in. Idempotent: undoing an unchecked registration is a no-op report. Not gated by the event's check-in window — undo corrects the host's own record rather than recording attendance. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access tok… - [Approve every pending guest](https://cal.com/docs/api-reference/v2/events/approve-every-pending-guest.md): Approves the Event's guests waiting for approval, optionally only those matching `search` or registered for `locationId`, as the roster's Approve all does. A free Event approves them in this request and returns `completed` with the counts. A paid Event sends each guest a payment request in the backg… - [Approve a guest](https://cal.com/docs/api-reference/v2/events/approve-a-guest.md): Approves one guest waiting for approval, as the roster's Approve does. On a free Event the guest gets a seat and `kind` is `confirmed`; when the Event is full the guest stays pending and `kind` is `event_full_offer_waitlist`. On a paid Event the guest is sent a payment request and `kind` is `payment… - [Decline a guest](https://cal.com/docs/api-reference/v2/events/decline-a-guest.md): Declines one guest waiting for approval or on the waitlist, as the roster's Decline does, and emails them. `kind` is `declined`. A guest can be declined even when the Event is cancelled. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the ownin… - [Check in a guest by scanned QR token](https://cal.com/docs/api-reference/v2/events/check-in-a-guest-by-scanned-qr-token.md): Redeems a scanned check-in QR token. The token is carried in the request body, never the URL, since URLs land in history and access logs. Same access as the by-id check-in; an external co-host may also work the door. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth acce… - [Message an Event's guests](https://cal.com/docs/api-reference/v2/events/message-an-events-guests.md): Emails one segment of the Event's guests, optionally narrowed to one location or to guests who did or did not check in. Guests who have only a phone number are texted instead when texting is available; `textRecipientCount` says how many. The message is queued and sent in the background, or at `sched… - [List the messages sent to an Event's guests](https://cal.com/docs/api-reference/v2/events/list-the-messages-sent-to-an-events-guests.md): Returns the Event's messages, newest first, with their delivery status. The authenticated user must be the Event's owner, one of its hosts, or a member of the owning team. Co-hosts cannot message guests. PBAC permission for team events: `calEvent.update`. Cursor-based pagination: pass `pagination.ne… - [Cancel a scheduled message](https://cal.com/docs/api-reference/v2/events/cancel-a-scheduled-message.md): Cancels a message that is still waiting for its `scheduledAt`, so nothing is sent. Once that time has come, or for a message sent at once, the cancel is refused. The authenticated user must be the Event's owner, one of its hosts, or a member of the owning team. Co-hosts cannot message guests. PBAC p… - [Invite guests to an Event](https://cal.com/docs/api-reference/v2/events/invite-guests-to-an-event.md): Emails an invitation to each address. Addresses that are already invited or registered are skipped, and the response reports what happened to every address. The Event must be published, not cancelled and not started yet, and the authenticated user must have a verified email. An Event holds at most 2… - [Search the team members who can host an Event](https://cal.com/docs/api-reference/v2/events/search-the-team-members-who-can-host-an-event.md): Returns the accepted members of the team that owns the Event, so you can pick who to send in `hosts` when updating the Event with `PATCH /v2/events/{uuid}`. Members whose invitation to the team is still pending are left out. `search` matches name or email, case-insensitive. - [List an Event's co-hosts](https://cal.com/docs/api-reference/v2/events/list-an-events-co-hosts.md): Returns the Event's co-hosts in their display order, with pending and declined invitations alongside accepted co-hosts. - [Invite a co-host to an Event](https://cal.com/docs/api-reference/v2/events/invite-a-co-host-to-an-event.md): Invites an email address to co-host the Event and emails it a link to accept, valid for 7 days. See `GET /v2/events/{uuid}/co-hosts` for what a co-host can do. - [Reorder an Event's co-hosts](https://cal.com/docs/api-reference/v2/events/reorder-an-events-co-hosts.md): Saves the display order of the Event's co-hosts. `coHostIds` must name every co-host on the Event, accepted and pending alike, exactly once; a list that went stale under a concurrent invite or removal is refused with 400 and nothing is saved. - [Remove a co-host from an Event](https://cal.com/docs/api-reference/v2/events/remove-a-co-host-from-an-event.md): Removes an accepted co-host, or cancels a pending invitation so its link stops working. - [Get an Event's coordinates](https://cal.com/docs/api-reference/v2/events/get-an-events-coordinates.md): Returns the `latitude` and `longitude` shown on the map of the Event's public page. Update them with `PATCH /v2/events/{uuid}/coordinates`. - [Update an Event's coordinates](https://cal.com/docs/api-reference/v2/events/update-an-events-coordinates.md): Moves where the Event's address location sits on the map of its public page and re-renders the map. - [Get an Event's locations](https://cal.com/docs/api-reference/v2/events/get-an-events-locations.md): Returns the Event's locations, each with its `id`, in the same shape as `locations` on `GET /v2/events/{uuid}`. A location this API version can't represent is returned as `type: "unknown"`. - [Add a location to an Event](https://cal.com/docs/api-reference/v2/events/add-a-location-to-an-event.md): Adds one location after the Event's existing locations and returns it with its `id`. Takes the same shape as an item of `locations` on `POST /v2/events`. Every existing location is kept as it is, including one this API version can't represent. - [Remove a location from an Event](https://cal.com/docs/api-reference/v2/events/remove-a-location-from-an-event.md): Removes one location and returns the Event's remaining locations, in the same shape as `GET /v2/events/{uuid}/locations`. Every other location is kept as it is, including one this API version can't represent. - [Edit an Event's location](https://cal.com/docs/api-reference/v2/events/edit-an-events-location.md): Changes the fields sent and keeps the rest of the location, including its `id`. `type` is required and must match the stored location; to change it, delete the location and add a new one. Pass null for `label`, `price` or `capacity` to remove it. A location returned as `type: "unknown"` can't be edi… #### Event Types Private Links - [Create a private link for an event type](https://cal.com/docs/api-reference/v2/event-types-private-links/create-a-private-link-for-an-event-type.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. - [Get all private links for an event type](https://cal.com/docs/api-reference/v2/event-types-private-links/get-all-private-links-for-an-event-type.md): If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. - [Update a private link for an event type](https://cal.com/docs/api-reference/v2/event-types-private-links/update-a-private-link-for-an-event-type.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. - [Delete a private link for an event type](https://cal.com/docs/api-reference/v2/event-types-private-links/delete-a-private-link-for-an-event-type.md): If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. #### Routing Forms - [Calculate slots based on routing form response](https://cal.com/docs/api-reference/v2/routing-forms/calculate-slots-based-on-routing-form-response.md): It will not actually save the response just return the routed event type and slots when it can be booked. #### Workflows - [Manage workflow paths](https://cal.com/docs/api-reference/v2/workflow-paths.md): Create and update conditional paths with API version 2026-09-22. - [Create a workflow](https://cal.com/docs/api-reference/v2/workflows/create-a-workflow.md): Create an event-type workflow owned by the authenticated user. Not available to third-party OAuth access tokens. - [Get your workflows](https://cal.com/docs/api-reference/v2/workflows/get-your-workflows.md): Get the event-type workflows owned by the authenticated user. Routing form workflows are not returned. Not available to third-party OAuth access tokens. - [Get your workflow](https://cal.com/docs/api-reference/v2/workflows/get-your-workflow.md): Get an event-type workflow owned by the authenticated user. Routing form workflows are not addressable through this endpoint. Not available to third-party OAuth access tokens. - [Get the fields a workflow's conditions can read](https://cal.com/docs/api-reference/v2/workflows/get-the-fields-a-workflows-conditions-can-read.md): List the fields a conditional path on this workflow can be written against, with the comparisons each one accepts and how both read in the Cal.com app. The catalog comes from what the workflow is active on — booking questions on its active event types — so it also reports the entities that do not as… - [Update your workflow](https://cal.com/docs/api-reference/v2/workflows/update-your-workflow.md): Update an event-type workflow owned by the authenticated user. Not available to third-party OAuth access tokens. - [Delete your workflow](https://cal.com/docs/api-reference/v2/workflows/delete-your-workflow.md): Delete an event-type workflow owned by the authenticated user. Not available to third-party OAuth access tokens. #### Webhooks - [Create a webhook](https://cal.com/docs/api-reference/v2/webhooks/create-a-webhook.md): If accessed using an OAuth access token, the `WEBHOOK_WRITE` scope is required. - [Get all webhooks](https://cal.com/docs/api-reference/v2/webhooks/get-all-webhooks.md): Gets a paginated list of webhooks for the authenticated user. If accessed using an OAuth access token, the `WEBHOOK_READ` scope is required. - [Update a webhook](https://cal.com/docs/api-reference/v2/webhooks/update-a-webhook.md): If accessed using an OAuth access token, the `WEBHOOK_WRITE` scope is required. - [Get a webhook](https://cal.com/docs/api-reference/v2/webhooks/get-a-webhook.md): If accessed using an OAuth access token, the `WEBHOOK_READ` scope is required. - [Delete a webhook](https://cal.com/docs/api-reference/v2/webhooks/delete-a-webhook.md): If accessed using an OAuth access token, the `WEBHOOK_WRITE` scope is required. #### Stripe - [Get Stripe connect URL](https://cal.com/docs/api-reference/v2/stripe/get-stripe-connect-url.md) - [Save Stripe credentials](https://cal.com/docs/api-reference/v2/stripe/save-stripe-credentials.md) - [Check Stripe connection](https://cal.com/docs/api-reference/v2/stripe/check-stripe-connection.md) ### TEAMS #### Teams - [Get teams](https://cal.com/docs/api-reference/v2/teams/get-teams.md): If accessed using an OAuth access token, the `TEAM_PROFILE_READ` scope is required. - [Get a team](https://cal.com/docs/api-reference/v2/teams/get-a-team.md): Required membership role: `team member`. PBAC permission: `team.readTeamSettings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_READ` scope is required. - [Update a team](https://cal.com/docs/api-reference/v2/teams/update-a-team.md): Required membership role: `team owner`. PBAC permission: `team.update`, or `organization.update` when the team id is an organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_WRITE` scope i… - [Delete a team](https://cal.com/docs/api-reference/v2/teams/delete-a-team.md): Required membership role: `team owner`. PBAC permission: `team.delete`, or `organization.delete` when the team id is an organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_WRITE` scope i… - [Get team bookings](https://cal.com/docs/api-reference/v2/teams-bookings/get-team-bookings.md): Required membership role: `team admin`. PBAC permission: `booking.readTeamBookings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_BOOKING_READ` scope is required. - [List a team's Events (cursor pagination)](https://cal.com/docs/api-reference/v2/teams-events/list-a-teams-events-cursor-pagination.md): Returns every Event the team owns, including ones the authenticated user neither hosts nor co-hosts. The user must be an accepted member of the team, or of its parent organization. PBAC permission: `calEvent.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-c… - [Create a team Event](https://cal.com/docs/api-reference/v2/teams-events/create-a-team-event.md): Creates a draft Event owned by the team. A draft is not public and nobody can register until it is published with `POST /v2/events/{uuid}/publish`. The user must be an accepted member of the team, or of its parent organization. PBAC permission: `calEvent.create`. Learn more about API access control… - [Get all team member schedules](https://cal.com/docs/api-reference/v2/teams-schedules/get-all-team-member-schedules.md): Required membership role: `team admin`. PBAC permission: `availability.readTeamAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_READ` scope is required. ##### Event Types - [Create a team event type](https://cal.com/docs/api-reference/v2/team-event-types/create-a-team-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [List team event types](https://cal.com/docs/api-reference/v2/team-event-types/list-team-event-types.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Get a team event type](https://cal.com/docs/api-reference/v2/team-event-types/get-a-team-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Update a team event type](https://cal.com/docs/api-reference/v2/team-event-types/update-a-team-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Delete a team event type](https://cal.com/docs/api-reference/v2/team-event-types/delete-a-team-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Create a phone call for a team event type](https://cal.com/docs/api-reference/v2/team-event-types/create-a-phone-call-for-a-team-event-type.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. ###### Booking Fields - [Get team booking fields](https://cal.com/docs/api-reference/v2/team-event-types/get-team-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Replace team booking fields](https://cal.com/docs/api-reference/v2/team-event-types/replace-team-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Add custom team booking fields](https://cal.com/docs/api-reference/v2/team-event-types/add-custom-team-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Update team booking fields](https://cal.com/docs/api-reference/v2/team-event-types/update-team-booking-fields.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. - [Delete a custom team booking field](https://cal.com/docs/api-reference/v2/team-event-types/delete-a-custom-team-booking-field.md): Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. ###### Webhooks - [Create a webhook for a team event type](https://cal.com/docs/api-reference/v2/teams-event-types-webhooks/create-a-webhook-for-a-team-event-type.md): If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [Get all webhooks for a team event type](https://cal.com/docs/api-reference/v2/teams-event-types-webhooks/get-all-webhooks-for-a-team-event-type.md): If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required. - [Delete all webhooks for a team event type](https://cal.com/docs/api-reference/v2/teams-event-types-webhooks/delete-all-webhooks-for-a-team-event-type.md): If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [Update a webhook for a team event type](https://cal.com/docs/api-reference/v2/teams-event-types-webhooks/update-a-webhook-for-a-team-event-type.md): If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [Get a webhook for a team event type](https://cal.com/docs/api-reference/v2/teams-event-types-webhooks/get-a-webhook-for-a-team-event-type.md): If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required. - [Delete a webhook for a team event type](https://cal.com/docs/api-reference/v2/teams-event-types-webhooks/delete-a-webhook-for-a-team-event-type.md): If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. ##### Booking Limit Pools - [List booking limit pools](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/list-booking-limit-pools.md): Returns the team's booking limit pools and its round-robin event types that can be in one. Requires an accepted membership of the team. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required. - [Create a booking limit pool](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/create-a-booking-limit-pool.md): Caps how many bookings each rotating host takes across the pool's round-robin event types. Set at least one interval. Requires permission to update the team's event types. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [Update a booking limit pool](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/update-a-booking-limit-pool.md): Changes only the fields sent. An interval sent as null is removed. Changing the mode or event types keeps every host's own limit. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [Delete a booking limit pool](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/delete-a-booking-limit-pool.md): Deletes the pool and the hosts' own limits for it. Its event types go back to their own per-host settings. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [List a pool's hosts and their limits](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/list-a-pools-hosts-and-their-limits.md): Returns the rotating hosts of the pool's event types in user id order, each with their own limit and the limit enforced for them. Requires permission to update the team's event types, since a host's limit can reveal their overall booking limit. If accessed using an OAuth access token, the `TEAM_EVEN… - [Set a host's limit for a pool](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/set-a-hosts-limit-for-a-pool.md): Sets the host's own limit for the intervals sent; null returns that interval to the pool's limit. Only intervals the pool limits can be set, and each is capped at the host's overall booking limit. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. - [Replace a host's limit for a pool](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/replace-a-hosts-limit-for-a-pool.md): Replaces the host's own limit with the intervals sent; an omitted interval returns to the pool's limit, so sending the same body again changes nothing. Only intervals the pool limits can be set, and each is capped at the host's overall booking limit. If accessed using an OAuth access token, the `TEA… - [Clear a host's limit for a pool](https://cal.com/docs/api-reference/v2/teams-booking-limit-pools/clear-a-hosts-limit-for-a-pool.md): Returns the host to the pool's limits. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required. ##### Invite - [Create team invite link](https://cal.com/docs/api-reference/v2/teams-invite/create-team-invite-link.md): Required membership role: `team admin`. PBAC permission: `team.invite`, or `organization.invite` when the team id is an organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scop… ##### Memberships - [Create a membership](https://cal.com/docs/api-reference/v2/teams-memberships/create-a-membership.md): Required membership role: `team admin`. PBAC permission: `team.invite`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required. - [Get all memberships](https://cal.com/docs/api-reference/v2/teams-memberships/get-all-memberships.md): Retrieve team memberships with optional filtering by email addresses. Supports pagination. Required membership role: `team admin`. PBAC permission: `team.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access t… - [Get a membership](https://cal.com/docs/api-reference/v2/teams-memberships/get-a-membership.md): Required membership role: `team admin`. PBAC permission: `team.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_READ` scope is required. - [Update membership](https://cal.com/docs/api-reference/v2/teams-memberships/update-membership.md): Required membership role: `team admin`. PBAC permission: `team.changeMemberRole`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required. - [Delete a membership](https://cal.com/docs/api-reference/v2/teams-memberships/delete-a-membership.md): Required membership role: `team admin`. PBAC permission: `team.remove`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required. ##### Routing Forms - [Create routing form response and get available slots](https://cal.com/docs/api-reference/v2/teams-routing-forms-responses/create-routing-form-response-and-get-available-slots.md): Only available for teams that are not part of an organization - for a team within an organization use the organization team endpoint instead. Required membership role: `team member`. PBAC permission: `routingForm.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/a… ##### Users / OOO - [Get all out-of-office entries for a team member](https://cal.com/docs/api-reference/v2/teams-users-ooo/get-all-out-of-office-entries-for-a-team-member.md): Required membership role: `team admin`. PBAC permission: `ooo.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_READ` scope is required. - [Create an out-of-office entry for a team member](https://cal.com/docs/api-reference/v2/teams-users-ooo/create-an-out-of-office-entry-for-a-team-member.md): Required membership role: `team admin`. PBAC permission: `ooo.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_WRITE` scope is required. - [Update an out-of-office entry for a team member](https://cal.com/docs/api-reference/v2/teams-users-ooo/update-an-out-of-office-entry-for-a-team-member.md): Required membership role: `team admin`. PBAC permission: `ooo.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_WRITE` scope is required. - [Delete an out-of-office entry for a team member](https://cal.com/docs/api-reference/v2/teams-users-ooo/delete-an-out-of-office-entry-for-a-team-member.md): Required membership role: `team admin`. PBAC permission: `ooo.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_WRITE` scope is required. #### Teams Verified Resources - [Request email verification code](https://cal.com/docs/api-reference/v2/teams-verified-resources/request-email-verification-code.md): Sends a verification code to the Email. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required. - [Request phone number verification code](https://cal.com/docs/api-reference/v2/teams-verified-resources/request-phone-number-verification-code.md): Sends a verification code to the phone number. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is re… - [Verify an email for a team](https://cal.com/docs/api-reference/v2/teams-verified-resources/verify-an-email-for-a-team.md): Use code to verify an email. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required. - [Verify a phone number for an org team](https://cal.com/docs/api-reference/v2/teams-verified-resources/verify-a-phone-number-for-an-org-team.md): Use code to verify a phone number. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required. - [Get list of verified emails of a team](https://cal.com/docs/api-reference/v2/teams-verified-resources/get-list-of-verified-emails-of-a-team.md): Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required. - [Get list of verified phone numbers of a team](https://cal.com/docs/api-reference/v2/teams-verified-resources/get-list-of-verified-phone-numbers-of-a-team.md): Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required. - [Get verified email of a team by id](https://cal.com/docs/api-reference/v2/teams-verified-resources/get-verified-email-of-a-team-by-id.md): Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required. - [Get verified phone number of a team by id](https://cal.com/docs/api-reference/v2/teams-verified-resources/get-verified-phone-number-of-a-team-by-id.md): Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required. ### AUTH & ACCESS #### API Keys - [Refresh API Key](https://cal.com/docs/api-reference/v2/api-keys/refresh-api-key.md): Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization header (e.g. "Authorization: Bearer "). #### OAuth2 - [Get OAuth2 client](https://cal.com/docs/api-reference/v2/oauth2/get-oauth2-client.md): Returns the OAuth2 client information for the given client ID - [Exchange authorization code or refresh token for tokens](https://cal.com/docs/api-reference/v2/oauth2/exchange-authorization-code-or-refresh-token-for-tokens.md): RFC 6749-compliant token endpoint. Pass client_id in the request body (Section 2.3.1). Use grant_type 'authorization_code' to exchange an auth code for tokens, or 'refresh_token' to refresh an access token. Accepts both application/x-www-form-urlencoded (standard per RFC 6749 Section 4.1.3) and appl… #### Verified Resources - [Request email verification code](https://cal.com/docs/api-reference/v2/verified-resources/request-email-verification-code.md): Sends a verification code to the email. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required. - [Request phone number verification code](https://cal.com/docs/api-reference/v2/verified-resources/request-phone-number-verification-code.md): Sends a verification code to the phone number. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required. - [Verify an email](https://cal.com/docs/api-reference/v2/verified-resources/verify-an-email.md): Use code to verify an email. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required. - [Verify a phone number](https://cal.com/docs/api-reference/v2/verified-resources/verify-a-phone-number.md): Use code to verify a phone number. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required. - [Get list of verified emails](https://cal.com/docs/api-reference/v2/verified-resources/get-list-of-verified-emails.md): If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required. - [Get list of verified phone numbers](https://cal.com/docs/api-reference/v2/verified-resources/get-list-of-verified-phone-numbers.md): If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required. - [Get verified email by id](https://cal.com/docs/api-reference/v2/verified-resources/get-verified-email-by-id.md): If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required. - [Get verified phone number by id](https://cal.com/docs/api-reference/v2/verified-resources/get-verified-phone-number-by-id.md): If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required. ### DEPRECATED #### Managed Orgs - [Create an organization within an organization](https://cal.com/docs/api-reference/v2/managed-orgs/create-an-organization-within-an-organization.md): For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control - [Get all organizations within an organization](https://cal.com/docs/api-reference/v2/managed-orgs/get-all-organizations-within-an-organization.md): For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.readManagedOrganizations`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control - [Get an organization within an organization](https://cal.com/docs/api-reference/v2/managed-orgs/get-an-organization-within-an-organization.md): For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.readManagedOrganizations`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control - [Update an organization within an organization](https://cal.com/docs/api-reference/v2/managed-orgs/update-an-organization-within-an-organization.md): For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control - [Delete an organization within an organization](https://cal.com/docs/api-reference/v2/managed-orgs/delete-an-organization-within-an-organization.md): For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control #### Platform OAuth Clients - [Create an OAuth client](https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/create-an-oauth-client.md): These endpoints are deprecated and will be removed in the future. - [Get all OAuth clients](https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/get-all-oauth-clients.md): These endpoints are deprecated and will be removed in the future. - [Get an OAuth client](https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/get-an-oauth-client.md): These endpoints are deprecated and will be removed in the future. - [Update an OAuth client](https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/update-an-oauth-client.md): These endpoints are deprecated and will be removed in the future. - [Delete an OAuth client](https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/delete-an-oauth-client.md): These endpoints are deprecated and will be removed in the future. #### Platform / Managed Users - [Get all managed users](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/get-all-managed-users.md): These endpoints are deprecated and will be removed in the future. - [Create a managed user](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/create-a-managed-user.md): These endpoints are deprecated and will be removed in the future. - [Get a managed user](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/get-a-managed-user.md): These endpoints are deprecated and will be removed in the future. - [Update a managed user](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/update-a-managed-user.md): These endpoints are deprecated and will be removed in the future. - [Delete a managed user](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/delete-a-managed-user.md): These endpoints are deprecated and will be removed in the future. - [Force refresh tokens](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/force-refresh-tokens.md): These endpoints are deprecated and will be removed in the future. If you have lost managed user access or refresh token, then you can get new ones by using OAuth credentials. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your databas… - [Refresh managed user tokens](https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/refresh-managed-user-tokens.md): These endpoints are deprecated and will be removed in the future. If managed user access token is expired then get a new one using this endpoint - it will also refresh the refresh token, because we use "refresh token rotation" mechanism. Access token is valid for 60 minutes an… #### Platform / Webhooks - [Create a webhook](https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/create-a-webhook.md): These endpoints are deprecated and will be removed in the future. - [Get all webhooks](https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/get-all-webhooks.md): These endpoints are deprecated and will be removed in the future. - [Delete all webhooks](https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/delete-all-webhooks.md): These endpoints are deprecated and will be removed in the future. - [Update a webhook](https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/update-a-webhook.md): These endpoints are deprecated and will be removed in the future. - [Get a webhook](https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/get-a-webhook.md): These endpoints are deprecated and will be removed in the future. - [Delete a webhook](https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/delete-a-webhook.md): These endpoints are deprecated and will be removed in the future. ## OpenAPI Specs - [openapi](/docs/api-reference/v2/openapi.json)