Getting Started
Platform / Cal Provider
Platform / Managed Users
Platform / Webhooks
Orgs / Attributes
Orgs / Attributes / Options
Orgs / Delegation Credentials
Orgs / Event Types
Orgs / Memberships
Orgs / Orgs
Orgs / Schedules
Orgs / Teams
Orgs / Teams / Bookings
Orgs / Teams / Memberships
Orgs / Teams / Routing forms / Responses
Orgs / Teams / Schedules
Orgs / Users / OOO
Orgs / Webhooks
Api Keys
Bookings
- GETGet all bookings
- POSTCreate a booking
- GETGet a booking
- POSTReschedule a booking
- POSTCancel a booking
- POSTMark a booking absence
- POSTAutomatically reassign booking to a new host
- POSTReassign a booking to a specific user
- POSTConfirm booking that requires a confirmation
- POSTDecline booking that requires a confirmation
- GETGet 'Add to Calendar' links for a booking
Calendars
Conferencing
Destination Calendars
Event Types
Event Types / Webhooks
OAuth Clients
Schedules
Selected Calendars
Slots
Stripe
Teams / Event Types
Teams / Memberships
Timezones
Create an event type
curl --request POST \
--url https://api.cal.com/v2/teams/{teamId}/event-types \
--header 'Content-Type: application/json' \
--data '{
"lengthInMinutes": 60,
"lengthInMinutesOptions": [
15,
30,
60
],
"title": "Learn the secrets of masterchief!",
"slug": "learn-the-secrets-of-masterchief",
"description": "Discover the culinary wonders of the Argentina by making the best flan ever!",
"bookingFields": [
{
"type": "name",
"label": "<string>",
"placeholder": "<string>",
"disableOnPrefill": true
}
],
"disableGuests": true,
"slotInterval": 123,
"minimumBookingNotice": 123,
"beforeEventBuffer": 123,
"afterEventBuffer": 123,
"scheduleId": 123,
"bookingLimitsCount": {
"day": 1,
"week": 2,
"month": 3,
"year": 4,
"disabled": false
},
"onlyShowFirstAvailableSlot": true,
"bookingLimitsDuration": {
"day": 60,
"week": 120,
"month": 180,
"year": 240
},
"bookingWindow": {
"type": "businessDays",
"value": 5,
"rolling": true
},
"offsetStart": 123,
"bookerLayouts": {
"defaultLayout": "month",
"enabledLayouts": [
"month"
]
},
"confirmationPolicy": {
"type": "always",
"noticeThreshold": {
"unit": "minutes",
"count": 30
},
"blockUnconfirmedBookingsInBooker": true
},
"recurrence": {
"interval": 10,
"occurrences": 10,
"frequency": "yearly"
},
"requiresBookerEmailVerification": true,
"hideCalendarNotes": true,
"lockTimeZoneToggleOnBookingPage": true,
"color": {
"lightThemeHex": "#292929",
"darkThemeHex": "#fafafa"
},
"seats": {
"seatsPerTimeSlot": 4,
"showAttendeeInfo": true,
"showAvailabilityCount": true
},
"customName": "{Event type title} between {Organiser} and {Scheduler}",
"destinationCalendar": {
"integration": "<string>",
"externalId": "<string>"
},
"useDestinationCalendarEmail": true,
"hideCalendarEventDetails": true,
"successRedirectUrl": "https://masterchief.com/argentina/flan/video/9129412",
"schedulingType": {},
"hosts": [
{
"userId": 123,
"mandatory": true,
"priority": "lowest"
}
],
"assignAllTeamMembers": true,
"locations": [
{
"type": "address",
"address": "123 Example St, City, Country",
"public": true
}
]
}'{
"status": "success",
"data": {
"id": 1,
"lengthInMinutes": 60,
"lengthInMinutesOptions": [
15,
30,
60
],
"title": "Learn the secrets of masterchief!",
"slug": "learn-the-secrets-of-masterchief",
"description": "Discover the culinary wonders of Argentina by making the best flan ever!",
"locations": [
{
"type": "address",
"address": "123 Example St, City, Country",
"public": true
}
],
"bookingFields": [
{
"type": "name",
"label": "<string>",
"placeholder": "<string>",
"disableOnPrefill": true,
"isDefault": true,
"slug": "<string>",
"required": true
}
],
"disableGuests": true,
"slotInterval": 60,
"minimumBookingNotice": 0,
"beforeEventBuffer": 0,
"afterEventBuffer": 0,
"recurrence": {
"interval": 10,
"occurrences": 10,
"frequency": "yearly"
},
"metadata": {},
"price": 123,
"currency": "<string>",
"lockTimeZoneToggleOnBookingPage": true,
"seatsPerTimeSlot": 123,
"forwardParamsSuccessRedirect": true,
"successRedirectUrl": "<string>",
"isInstantEvent": true,
"seatsShowAvailabilityCount": true,
"scheduleId": 123,
"bookingLimitsCount": {},
"onlyShowFirstAvailableSlot": true,
"bookingLimitsDuration": {},
"bookingWindow": [
{
"type": "businessDays",
"value": 5,
"rolling": true
}
],
"bookerLayouts": {
"defaultLayout": "month",
"enabledLayouts": [
"month"
]
},
"confirmationPolicy": {},
"requiresBookerEmailVerification": true,
"hideCalendarNotes": true,
"color": {
"lightThemeHex": "#292929",
"darkThemeHex": "#fafafa"
},
"seats": {
"seatsPerTimeSlot": 4,
"showAttendeeInfo": true,
"showAvailabilityCount": true
},
"offsetStart": 2,
"customName": "<string>",
"destinationCalendar": {
"integration": "<string>",
"externalId": "<string>"
},
"useDestinationCalendarEmail": true,
"hideCalendarEventDetails": true,
"teamId": 123,
"ownerId": 123,
"parentEventTypeId": 123,
"hosts": [
{
"userId": 123,
"mandatory": true,
"priority": "lowest",
"name": "John Doe",
"avatarUrl": "https://cal.com/api/avatar/d95949bc-ccb1-400f-acf6-045c51a16856.png"
}
],
"assignAllTeamMembers": true,
"schedulingType": "ROUND_ROBIN",
"team": {
"id": 123,
"slug": "<string>",
"bannerUrl": "<string>",
"name": "<string>",
"logoUrl": "<string>",
"weekStart": "<string>",
"brandColor": "<string>",
"darkBrandColor": "<string>",
"theme": "<string>"
}
}
}Path Parameters
Body
60
"Learn the secrets of masterchief!"
"learn-the-secrets-of-masterchief"
If you want that user can choose between different lengths of the event you can specify them here. Must include the provided lengthInMinutes.
[15, 30, 60]
"Discover the culinary wonders of the Argentina by making the best flan ever!"
Custom fields that can be added to the booking form when the event is booked by someone. By default booking form has name and email field.
only allowed value for type is name. Used for having 1 booking field for both first name and last name.
"name"
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 &name=bob, the name field will be prefilled with this value and disabled.
If true, person booking this event can't add guests via their emails.
Number representing length of each slot when event is booked. By default it equal length of the event type. If event length is 60 minutes then we would have slots 9AM, 10AM, 11AM etc. but if it was changed to 30 minutes then we would have slots 9AM, 9:30AM, 10AM, 10:30AM etc. as the available times to book the 60 minute event.
Minimum number of minutes before the event that a booking can be made.
Time spaces that can be prepended before an event to give more time before it.
Time spaces that can be appended after an event to give more time after it.
If you want that this event has different schedule than user's default one you can specify it here.
Limit how many times this event can be booked
The number of bookings per day
1
The number of bookings per week
2
The number of bookings per month
3
The number of bookings per year
4
This will limit your availability for this event type to one slot per day, scheduled at the earliest available time.
Limit total amount of time that this event can be booked
The duration of bookings per day (must be a multiple of 15)
60
The duration of bookings per week (must be a multiple of 15)
120
The duration of bookings per month (must be a multiple of 15)
180
The duration of bookings per year (must be a multiple of 15)
240
Limit how far in the future this event can be booked
Whether the window should be business days, calendar days or a range of dates
businessDays, calendarDays, range How many business day into the future can this event be booked
5
Determines the behavior of the booking window:
- If **true**, the window is rolling. This means the number of available days will always be equal the specified 'value'
and adjust dynamically as bookings are made. For example, if 'value' is 3 and availability is only on Mondays,
a booker attempting to schedule on November 10 will see slots on November 11, 18, and 25. As one of these days
becomes fully booked, a new day (e.g., December 2) will open up to ensure 3 available days are always visible.
- If **false**, the window is fixed. This means the booking window only considers the next 'value' days from the
moment someone is trying to book. For example, if 'value' is 3, availability is only on Mondays, and the current
date is November 10, the booker will only see slots on November 11 because the window is restricted to the next
3 calendar days (November 10–12).
true
Offset timeslots shown to bookers by a specified number of minutes
Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.
The policy that determines when confirmation is required
always, time "always"
Unconfirmed bookings still block calendar slots.
The notice threshold required before confirmation is needed. Required when type is 'time'.
Create an event type with multiple seats.
Customizable event name with valid variables: {Event type title}, {Organiser}, {Scheduler}, {Location}, {Organiser first name}, {Scheduler first name}, {Scheduler last name}, {Event duration}, {LOCATION}, {HOST/ATTENDEE}, {HOST}, {ATTENDEE}, {USER}
"{Event type title} between {Organiser} and {Scheduler}"
The integration type of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the integration type of your connected calendars.
The external ID of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the external IDs of your connected calendars.
A valid URL where the booker will redirect to, once the booking is completed successfully
"https://masterchief.com/argentina/flan/video/9129412"
If true, all current and future team members will be assigned to this event type
Response
success, error "success"
1
x >= 160
"Learn the secrets of masterchief!"
"learn-the-secrets-of-masterchief"
"Discover the culinary wonders of Argentina by making the best flan ever!"
only allowed value for type is address
address, link, integration, phone, attendeeAddress, attendeePhone, attendeeDefined, organizersDefaultApp "address"
"123 Example St, City, Country"
only allowed value for type is name. Used for having 1 booking field for both first name and last name.
name, email, phone, address, text, number, textarea, select, multiselect, multiemail, checkbox, radio, boolean, url "name"
This property is always true because it's a default field
true
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 &name=bob, the name field will be prefilled with this value and disabled.
Which user is the host of this event
"John Doe"
Only relevant for round robin event types. If true then the user must attend round robin event always.
lowest, low, medium, high, highest "https://cal.com/api/avatar/d95949bc-ccb1-400f-acf6-045c51a16856.png"
ROUND_ROBIN, COLLECTIVE, MANAGED If you want that user can choose between different lengths of the event you can specify them here. Must include the provided lengthInMinutes.
[15, 30, 60]
60
x >= 00
x >= 00
x >= 00
Limit how far in the future this event can be booked
Whether the window should be business days, calendar days or a range of dates
businessDays, calendarDays, range How many business day into the future can this event be booked
5
Determines the behavior of the booking window:
- If **true**, the window is rolling. This means the number of available days will always be equal the specified 'value'
and adjust dynamically as bookings are made. For example, if 'value' is 3 and availability is only on Mondays,
a booker attempting to schedule on November 10 will see slots on November 11, 18, and 25. As one of these days
becomes fully booked, a new day (e.g., December 2) will open up to ensure 3 available days are always visible.
- If **false**, the window is fixed. This means the booking window only considers the next 'value' days from the
moment someone is trying to book. For example, if 'value' is 3, availability is only on Mondays, and the current
date is November 10, the booker will only see slots on November 11 because the window is restricted to the next
3 calendar days (November 10–12).
true
x >= 1The integration type of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the integration type of your connected calendars.
The external ID of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the external IDs of your connected calendars.
For managed event types, parent event type is the event type that this event type is based on
Was this page helpful?
curl --request POST \
--url https://api.cal.com/v2/teams/{teamId}/event-types \
--header 'Content-Type: application/json' \
--data '{
"lengthInMinutes": 60,
"lengthInMinutesOptions": [
15,
30,
60
],
"title": "Learn the secrets of masterchief!",
"slug": "learn-the-secrets-of-masterchief",
"description": "Discover the culinary wonders of the Argentina by making the best flan ever!",
"bookingFields": [
{
"type": "name",
"label": "<string>",
"placeholder": "<string>",
"disableOnPrefill": true
}
],
"disableGuests": true,
"slotInterval": 123,
"minimumBookingNotice": 123,
"beforeEventBuffer": 123,
"afterEventBuffer": 123,
"scheduleId": 123,
"bookingLimitsCount": {
"day": 1,
"week": 2,
"month": 3,
"year": 4,
"disabled": false
},
"onlyShowFirstAvailableSlot": true,
"bookingLimitsDuration": {
"day": 60,
"week": 120,
"month": 180,
"year": 240
},
"bookingWindow": {
"type": "businessDays",
"value": 5,
"rolling": true
},
"offsetStart": 123,
"bookerLayouts": {
"defaultLayout": "month",
"enabledLayouts": [
"month"
]
},
"confirmationPolicy": {
"type": "always",
"noticeThreshold": {
"unit": "minutes",
"count": 30
},
"blockUnconfirmedBookingsInBooker": true
},
"recurrence": {
"interval": 10,
"occurrences": 10,
"frequency": "yearly"
},
"requiresBookerEmailVerification": true,
"hideCalendarNotes": true,
"lockTimeZoneToggleOnBookingPage": true,
"color": {
"lightThemeHex": "#292929",
"darkThemeHex": "#fafafa"
},
"seats": {
"seatsPerTimeSlot": 4,
"showAttendeeInfo": true,
"showAvailabilityCount": true
},
"customName": "{Event type title} between {Organiser} and {Scheduler}",
"destinationCalendar": {
"integration": "<string>",
"externalId": "<string>"
},
"useDestinationCalendarEmail": true,
"hideCalendarEventDetails": true,
"successRedirectUrl": "https://masterchief.com/argentina/flan/video/9129412",
"schedulingType": {},
"hosts": [
{
"userId": 123,
"mandatory": true,
"priority": "lowest"
}
],
"assignAllTeamMembers": true,
"locations": [
{
"type": "address",
"address": "123 Example St, City, Country",
"public": true
}
]
}'{
"status": "success",
"data": {
"id": 1,
"lengthInMinutes": 60,
"lengthInMinutesOptions": [
15,
30,
60
],
"title": "Learn the secrets of masterchief!",
"slug": "learn-the-secrets-of-masterchief",
"description": "Discover the culinary wonders of Argentina by making the best flan ever!",
"locations": [
{
"type": "address",
"address": "123 Example St, City, Country",
"public": true
}
],
"bookingFields": [
{
"type": "name",
"label": "<string>",
"placeholder": "<string>",
"disableOnPrefill": true,
"isDefault": true,
"slug": "<string>",
"required": true
}
],
"disableGuests": true,
"slotInterval": 60,
"minimumBookingNotice": 0,
"beforeEventBuffer": 0,
"afterEventBuffer": 0,
"recurrence": {
"interval": 10,
"occurrences": 10,
"frequency": "yearly"
},
"metadata": {},
"price": 123,
"currency": "<string>",
"lockTimeZoneToggleOnBookingPage": true,
"seatsPerTimeSlot": 123,
"forwardParamsSuccessRedirect": true,
"successRedirectUrl": "<string>",
"isInstantEvent": true,
"seatsShowAvailabilityCount": true,
"scheduleId": 123,
"bookingLimitsCount": {},
"onlyShowFirstAvailableSlot": true,
"bookingLimitsDuration": {},
"bookingWindow": [
{
"type": "businessDays",
"value": 5,
"rolling": true
}
],
"bookerLayouts": {
"defaultLayout": "month",
"enabledLayouts": [
"month"
]
},
"confirmationPolicy": {},
"requiresBookerEmailVerification": true,
"hideCalendarNotes": true,
"color": {
"lightThemeHex": "#292929",
"darkThemeHex": "#fafafa"
},
"seats": {
"seatsPerTimeSlot": 4,
"showAttendeeInfo": true,
"showAvailabilityCount": true
},
"offsetStart": 2,
"customName": "<string>",
"destinationCalendar": {
"integration": "<string>",
"externalId": "<string>"
},
"useDestinationCalendarEmail": true,
"hideCalendarEventDetails": true,
"teamId": 123,
"ownerId": 123,
"parentEventTypeId": 123,
"hosts": [
{
"userId": 123,
"mandatory": true,
"priority": "lowest",
"name": "John Doe",
"avatarUrl": "https://cal.com/api/avatar/d95949bc-ccb1-400f-acf6-045c51a16856.png"
}
],
"assignAllTeamMembers": true,
"schedulingType": "ROUND_ROBIN",
"team": {
"id": 123,
"slug": "<string>",
"bannerUrl": "<string>",
"name": "<string>",
"logoUrl": "<string>",
"weekStart": "<string>",
"brandColor": "<string>",
"darkBrandColor": "<string>",
"theme": "<string>"
}
}
}