openapi: 3.0.0
info:
title: Cal.diy API v2 Api Keys Event Types API
description: ''
version: 1.0.0
contact: {}
servers: []
tags:
- name: Event Types
paths:
/v2/event-types:
post:
operationId: EventTypesController_2024_06_14_createEventType
summary: Create an event type
description: <Note>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.</Note>
parameters:
- name: cal-api-version
in: header
description: Must be set to 2024-06-14. If not set to this value, the endpoint will default to an older version.
required: true
schema:
type: string
default: '2024-06-14'
- name: Authorization
in: header
description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEventTypeInput_2024_06_14'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEventTypeOutput_2024_06_14'
tags:
- Event Types
get:
operationId: EventTypesController_2024_06_14_getEventTypes
summary: Get all event types
description: "Hidden event types are returned only if authentication is provided and it belongs to the event type owner.\n \n Use the optional `sortCreatedAt` query parameter to order results by creation date (by ID). Accepts \"asc\" (oldest first) or \"desc\" (newest first). When not provided, no explicit ordering is applied.\n \n <Note>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.</Note>\n "
parameters:
- name: cal-api-version
in: header
description: Must be set to 2024-06-14. If not set to this value, the endpoint will default to an older version.
required: true
schema:
type: string
default: '2024-06-14'
- name: username
required: false
in: query
description: The username of the user to get event types for. If only username provided will get all event types.
schema:
type: string
- name: eventSlug
required: false
in: query
description: Slug of event type to return. Notably, if eventSlug is provided then username must be provided too, because multiple users can have event with same slug.
schema:
type: string
- name: usernames
required: false
in: query
description: Get dynamic event type for multiple usernames separated by comma. e.g `usernames=alice,bob`
schema:
type: string
- name: orgSlug
required: false
in: query
description: slug of the user's organization if he is in one, orgId is not required if using this parameter
schema:
type: string
- name: orgId
required: false
in: query
description: ID of the organization of the user you want the get the event-types of, orgSlug is not needed when using this parameter
schema:
type: number
- name: sortCreatedAt
required: false
in: query
description: Sort event types by creation date. When not provided, no explicit ordering is applied.
schema:
enum:
- asc
- desc
type: string
- name: Authorization
in: header
description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
required: false
schema:
type: string
- name: x-cal-secret-key
in: header
description: For platform customers - OAuth client secret key
required: false
schema:
type: string
- name: x-cal-client-id
in: header
description: For platform customers - OAuth client ID
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventTypesOutput_2024_06_14'
tags:
- Event Types
/v2/event-types/{eventTypeId}:
get:
operationId: EventTypesController_2024_06_14_getEventTypeById
summary: Get an event type
description: "<Note>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.</Note>\n \n Access control: This endpoint fetches an event type by ID and returns it only if the authenticated user is authorized. Authorization is granted to:\n - System admins\n - The event type owner\n - Hosts of the event type or users assigned to the event type\n - Team admins/owners of the team that owns the team event type\n - Organization admins/owners of the event type owner's organization\n - Organization admins/owners of the team's parent organization\n\n Note: Update and delete endpoints remain restricted to the event type owner only."
parameters:
- name: cal-api-version
in: header
description: Must be set to 2024-06-14. If not set to this value, the endpoint will default to an older version.
required: true
schema:
type: string
default: '2024-06-14'
- name: eventTypeId
required: true
in: path
schema:
type: string
- name: Authorization
in: header
description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventTypeOutput_2024_06_14'
tags:
- Event Types
patch:
operationId: EventTypesController_2024_06_14_updateEventType
summary: Update an event type
description: <Note>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.</Note>
parameters:
- name: cal-api-version
in: header
description: Must be set to 2024-06-14. If not set to this value, the endpoint will default to an older version.
required: true
schema:
type: string
default: '2024-06-14'
- name: eventTypeId
required: true
in: path
schema:
type: number
- name: Authorization
in: header
description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEventTypeInput_2024_06_14'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEventTypeOutput_2024_06_14'
tags:
- Event Types
delete:
operationId: EventTypesController_2024_06_14_deleteEventType
summary: Delete an event type
description: <Note>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.</Note>
parameters:
- name: cal-api-version
in: header
description: Must be set to 2024-06-14. If not set to this value, the endpoint will default to an older version.
required: true
schema:
type: string
default: '2024-06-14'
- name: eventTypeId
required: true
in: path
schema:
type: number
- name: Authorization
in: header
description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEventTypeOutput_2024_06_14'
tags:
- Event Types
components:
schemas:
BookerActiveBookingsLimit_2024_06_14:
type: object
properties:
maximumActiveBookings:
type: number
description: The maximum number of active bookings a booker can have for this event type.
example: 3
offerReschedule:
type: boolean
description: Whether to offer rescheduling the last active booking to the chosen time slot when limit is reached.
PhoneFieldInput_2024_06_14:
type: object
properties:
type:
type: string
example: phone
description: only allowed value for type is `phone`
slug:
type: string
description: "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking. Special slug is `attendeePhoneNumber` - if you create\n a phone input field with this slug for organization team event type you can create an organization team event type that can be booked using phone without requiring an email by setting {\"type\": \"email\", \"required\": false, \"hidden\": true} to the email booking field input in the request body."
example: some-slug
label:
type: string
required:
type: boolean
placeholder:
type: string
disableOnPrefill:
type: boolean
description: 'Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if the slug is `phone` and the URL contains query parameter `&phone=1234567890`, the phone field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{phone: ''+37122222222''}}`. See guide https://cal.com/docs/platform/guides/booking-field'
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
required:
- type
- slug
- label
- required
- placeholder
- hidden
Seats_2024_06_14:
type: object
properties:
seatsPerTimeSlot:
type: number
description: Number of seats available per time slot
example: 4
showAttendeeInfo:
type: boolean
description: Show attendee information to other guests
example: true
showAvailabilityCount:
type: boolean
description: Display the count of available seats
example: true
required:
- seatsPerTimeSlot
- showAttendeeInfo
- showAvailabilityCount
RangeWindow_2024_06_14:
type: object
properties:
type:
type: string
enum:
- businessDays
- calendarDays
- range
description: Whether the window should be business days, calendar days or a range of dates
value:
example:
- '2030-09-05'
- '2030-09-09'
description: Date range for when this event can be booked.
type: array
items:
type: string
required:
- type
- value
GuestsDefaultFieldInput_2024_06_14:
type: object
properties:
slug:
type: string
example: guests
description: only allowed value for type is `guests`
required:
type: boolean
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
label:
type: string
placeholder:
type: string
disableOnPrefill:
type: boolean
description: 'Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if URL contains query parameter `&guests=bob@cal.com`, the guests field will be prefilled with this value and disabled. In case of Booker atom need to pass ''guests'' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{guests: [''bob@gmail.com'', ''alice@gmail.com'']}}`. See guide https://cal.com/docs/platform/guides/booking-field'
required:
- slug
UrlFieldInput_2024_06_14:
type: object
properties:
type:
type: string
example: url
description: only allowed value for type is `url`
slug:
type: string
description: Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking
example: some-slug
label:
type: string
example: Please enter your text
required:
type: boolean
placeholder:
type: string
example: e.g., Enter url here
disableOnPrefill:
type: boolean
description: 'Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if the slug is `videourl` and the URL contains query parameter `&videourl=https://youtube.com/abc`the url field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{videourl: ''https://caltube.com/123''}}`. See guide https://cal.com/docs/platform/guides/booking-field'
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
required:
- type
- slug
- label
- required
- placeholder
- hidden
NumberFieldOutput_2024_06_14:
type: object
properties:
type:
type: string
example: number
description: only allowed value for type is `number`
slug:
type: string
description: Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking
example: some-slug
label:
type: string
example: Please enter a number
required:
type: boolean
placeholder:
type: string
example: e.g., 100
disableOnPrefill:
type: boolean
description: 'Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if the slug is `calories` and the URL contains query parameter `&calories=3000`, the number field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{calories: 3000}}`. See guide https://cal.com/docs/platform/guides/booking-field'
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
isDefault:
type: object
description: This property is always false because it's not default field but custom field
example: false
default: false
required:
- type
- slug
- label
- required
- placeholder
- hidden
- isDefault
DisableCancellingOutput_2024_06_14:
type: object
properties:
disabled:
type: boolean
description: If true, cancelling is always disabled for this event type.
example: true
RescheduleReasonDefaultFieldOutput_2024_06_14:
type: object
properties:
slug:
type: string
example: rescheduleReason
description: only allowed value for type is `rescheduleReason`
default: rescheduleReason
required:
type: boolean
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
label:
type: string
placeholder:
type: string
disableOnPrefill:
type: boolean
description: Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if URL contains query parameter `&rescheduleReason=busy`, the reschedule reason field will be prefilled with this value and disabled.
isDefault:
type: object
description: This property is always true because it's a default field
example: true
default: true
type:
type: string
default: textarea
required:
- slug
- isDefault
- type
MultiSelectFieldOutput_2024_06_14:
type: object
properties:
type:
type: string
example: multiselect
description: only allowed value for type is `multiselect`
slug:
type: string
description: Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking
example: some-slug
label:
type: string
example: Please select multiple options
required:
type: boolean
options:
example:
- Option 1
- Option 2
type: array
items:
type: string
disableOnPrefill:
type: boolean
description: 'Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if the slug is `language` and the URL contains query parameter `&language=en&language=it`, the ''en'' and ''it'' will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{language: [''en'', ''it'']}}`. See guide https://cal.com/docs/platform/guides/booking-field'
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
isDefault:
type: object
description: This property is always false because it's not default field but custom field
example: false
default: false
required:
- type
- slug
- label
- required
- options
- hidden
- isDefault
BooleanFieldOutput_2024_06_14:
type: object
properties:
type:
type: string
example: boolean
description: only allowed value for type is `boolean`
slug:
type: string
description: Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking
example: some-slug
label:
type: string
example: Agree to terms?
required:
type: boolean
disableOnPrefill:
type: boolean
description: 'Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value. For example, if the slug is `notify` and the URL contains query parameter `¬ify=true`, the checkbox will be selected and the checkbox field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{notify: true}}`. See guide https://cal.com/docs/platform/guides/booking-field'
hidden:
type: boolean
description: If true show under event type settings but don't show this booking field in the Booker. If false show in both.
isDefault:
type: object
description: This property is always false because it's not default field but custom field
example: false
default: false
required:
- type
- slug
- label
- required
- hidden
- isDefault
UpdateEventTypeInput_2024_06_14:
type: object
properties:
lengthInMinutes:
type: number
example: 60
lengthInMinutesOptions:
example:
- 15
- 30
- 60
description: If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.
type: array
items:
type: string
title:
type: string
example: Learn the secrets of masterchief!
slug:
type: string
example: learn-the-secrets-of-masterchief
description:
type: string
example: Discover the culinary wonders of the Argentina by making the best flan ever!
bookingFields:
type: array
description: Complete set of booking form fields. This array replaces all existing booking fields. To modify existing fields, first fetch the current event type, then include all desired fields in this array. Sending only one field will remove all other custom fields, keeping only default fields plus the provided one.
items:
oneOf:
- $ref: '#/components/schemas/NameDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/EmailDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/TitleDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/LocationDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/NotesDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/GuestsDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/RescheduleReasonDefaultFieldInput_2024_06_14'
- $ref: '#/components/schemas/PhoneFieldInput_2024_06_14'
- $ref: '#/components/schemas/AddressFieldInput_2024_06_14'
- $ref: '#/components/schemas/TextFieldInput_2024_06_14'
- $ref: '#/components/schemas/NumberFieldInput_2024_06_14'
- $ref: '#/components/schemas/TextAreaFieldInput_2024_06_14'
- $ref: '#/components/schemas/SelectFieldInput_2024_06_14'
- $ref: '#/components/schemas/MultiSelectFieldInput_2024_06_14'
- $ref: '#/components/schemas/MultiEmailFieldInput_2024_06_14'
- $ref: '#/components/schemas/CheckboxGroupFieldInput_2024_06_14'
- $ref: '#/components/schemas/RadioGroupFieldInput_2024_06_14'
- $ref: '#/components/schemas/BooleanFieldInput_2024_06_14'
disableGuests:
type: boolean
description: If true, person booking this event can't add guests via their emails.
slotInterval:
type: number
description: "Number representing length of each slot when event is booked. By default it equal length of the event type.\n If event length is 60 minutes then we would have slots 9AM, 10AM, 11AM etc. but if it was changed to 30 minutes then\n we would have slots 9AM, 9:30AM, 10AM, 10:30AM etc. as the available times to book the 60 minute event."
minimumBookingNotice:
type: number
description: Minimum number of minutes before the event that a booking can be made.
beforeEventBuffer:
type: number
description: Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity.
afterEventBuffer:
type: number
description: Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment.
scheduleId:
type: number
description: If you want that this event has different schedule than user's default one you can specify it here.
bookingLimitsCount:
description: Limit how many times this event can be booked
oneOf:
- $ref: '#/components/schemas/BaseBookingLimitsCount_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
bookerActiveBookingsLimit:
description: Limit the number of active bookings a booker can make for this event type.
oneOf:
- $ref: '#/components/schemas/BookerActiveBookingsLimit_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
onlyShowFirstAvailableSlot:
type: boolean
description: This will limit your availability for this event type to one slot per day, scheduled at the earliest available time.
bookingLimitsDuration:
description: Limit total amount of time that this event can be booked
oneOf:
- $ref: '#/components/schemas/BaseBookingLimitsDuration_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
bookingWindow:
description: Limit how far in the future this event can be booked
oneOf:
- $ref: '#/components/schemas/BusinessDaysWindow_2024_06_14'
- $ref: '#/components/schemas/CalendarDaysWindow_2024_06_14'
- $ref: '#/components/schemas/RangeWindow_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
offsetStart:
type: number
description: Offset timeslots shown to bookers by a specified number of minutes
bookerLayouts:
description: Should booker have week, month or column view. Specify default layout and enabled layouts user can pick.
allOf:
- $ref: '#/components/schemas/BookerLayouts_2024_06_14'
confirmationPolicy:
description: Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.
oneOf:
- $ref: '#/components/schemas/BaseConfirmationPolicy_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
recurrence:
description: Create a recurring event type.
oneOf:
- $ref: '#/components/schemas/Recurrence_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
requiresBookerEmailVerification:
type: boolean
hideCalendarNotes:
type: boolean
lockTimeZoneToggleOnBookingPage:
type: boolean
color:
$ref: '#/components/schemas/EventTypeColor_2024_06_14'
seats:
description: Create an event type with multiple seats.
oneOf:
- $ref: '#/components/schemas/Seats_2024_06_14'
- $ref: '#/components/schemas/Disabled_2024_06_14'
customName:
type: string
description: "Customizable event name with valid variables:\n {Event type title}, {Organiser}, {Scheduler}, {Location}, {Organiser first name},\n {Scheduler first name}, {Scheduler last name}, {Event duration}, {LOCATION},\n {HOST/ATTENDEE}, {HOST}, {ATTENDEE}, {USER}"
example: '{Event type title} between {Organiser} and {Scheduler}'
destinationCalendar:
$ref: '#/components/schemas/DestinationCalendar_2024_06_14'
useDestinationCalendarEmail:
type: boolean
hideCalendarEventDetails:
type: boolean
successRedirectUrl:
type: string
description: A valid URL where the booker will redirect to, once the booking is completed successfully
example: https://masterchief.com/argentina/flan/video/9129412
hideOrganizerEmail:
type: boolean
description: Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events
calVideoSettings:
description: Cal video settings for the event type
allOf:
- $ref: '#/components/schemas/CalVideoSettings'
hidden:
type: boolean
bookingRequiresAuthentication:
type: boolean
default: false
description: Boolean to require authentication for booking this event type via api. If true, only authenticated users who are the event-type owner or org/team admin/owner can book this event type.
disableCancelling:
description: Settings for disabling cancelling of this event type.
example:
disabled: true
allOf:
- $ref: '#/components/schemas/DisableCancelling_2024_06_14'
disableRescheduling:
description: Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.
example:
disabled: false
minutesBefore: 60
allOf:
- $ref: '#/components/schemas/DisableRescheduling_2024_06_14'
interfaceLanguage:
type: string
description: Set preferred language for the booking interface. Use empty string for visitor's browser language (default).
enum:
- ''
- en
- ar
- az
- bg
- bn
- ca
- cs
- da
- de
- el
- es
- es-419
- eu
- et
- fi
- fr
- he
- hu
- it
- ja
- km
- ko
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk-SK
- sr
- sv
- tr
- uk
- vi
- zh-CN
- zh-TW
allowReschedulingPastBookings:
type: boolean
description: Enabling this option allows for past events to be rescheduled.
default: false
allowReschedulingCancelledBookings:
type: boolean
description: When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking.
default: false
showOptimizedSlots:
type: boolean
description: Arrange time slots to optimize availability.
default: false
locations:
type: array
description: 'Locations where the event will take place. If not provided, cal video link will be used as the location. Note: Setting a location to a conferencing app does not install the app - the app must already be installed. Via API, only Google Meet (google-meet), Microsoft Teams (office365-video), and Zoom (zoom) can be installed. Cal Video (cal-video) is installed by default. All other conferencing apps must be connected via the Cal.diy web app and are not available for Platform plan customers. You can only set an event type location to an app that has already been installed or connected.'
items:
oneOf:
- $ref: '#/components/schemas/InputAddressLocation_2024_06_14'
- $ref: '#/components/schemas/InputLinkLocation_2024_06_14'
- $ref: '#/components/schemas/InputIntegrationLocation_2024_06_14'
- $ref: '#/components/schemas/InputPhoneLocation_2024_06_14'
- $ref: '#/components/schema
# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cal-com/refs/heads/main/openapi/cal-com-event-types-api-openapi.yml