Create an event type

Headers

Authorization

string

For non-platform customers - value must be Bearer <token> where <token> is api key prefixed with cal_

x-cal-secret-key

string

For platform customers - OAuth client secret key

x-cal-client-id

string

For platform customers - OAuth client ID

Path Parameters

teamId

number

required

orgId

number

required

Body

application/json

lengthInMinutes

number

required

Example:

60

title

string

required

Example:

"Learn the secrets of masterchief!"

slug

string

required

Example:

"learn-the-secrets-of-masterchief"

schedulingType

enum<string>

required

The scheduling type for the team event - collective, roundRobin or managed.

Available options:

collective,

roundRobin,

managed

Example:

"collective"

lengthInMinutesOptions

string[]

If you want that user can choose between different lengths of the event you can specify them here. Must include the provided lengthInMinutes.

Example:

[15, 30, 60]

description

string

Example:

"Discover the culinary wonders of the Argentina by making the best flan ever!"

bookingFields

object[]

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.

• Option 1
• Option 2
• Option 3
• Option 4
• Option 5
• Option 6
• Option 7
• Option 8
• Option 9
• Option 10
• Option 11
• Option 12
• Option 13
• Option 14
• Option 15
• Option 16
• Option 17
• Option 18

Show child attributes

bookingFields.type

string

required

only allowed value for type is name. Used for having 1 booking field for both first name and last name.

Example:

"name"

bookingFields.label

string

required

bookingFields.placeholder

string

required

bookingFields.disableOnPrefill

boolean

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.

disableGuests

boolean

If true, person booking this event can't add guests via their emails.

slotInterval

number

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.

minimumBookingNotice

number

Minimum number of minutes before the event that a booking can be made.

beforeEventBuffer

number

Time spaces that can be prepended before an event to give more time before it.

afterEventBuffer

number

Time spaces that can be appended after an event to give more time after it.

scheduleId

number

If you want that this event has different schedule than user's default one you can specify it here.

bookingLimitsCount

object

Limit how many times this event can be booked

• Option 1
• Option 2

Show child attributes

bookingLimitsCount.day

number

The number of bookings per day

Example:

1

bookingLimitsCount.week

number

The number of bookings per week

Example:

2

bookingLimitsCount.month

number

The number of bookings per month

Example:

3

bookingLimitsCount.year

number

The number of bookings per year

Example:

4

bookingLimitsCount.disabled

boolean

default:false

onlyShowFirstAvailableSlot

boolean

This will limit your availability for this event type to one slot per day, scheduled at the earliest available time.

bookingLimitsDuration

object

Limit total amount of time that this event can be booked

• Option 1
• Option 2

Show child attributes

bookingLimitsDuration.day

number

The duration of bookings per day (must be a multiple of 15)

Example:

60

bookingLimitsDuration.week

number

The duration of bookings per week (must be a multiple of 15)

Example:

120

bookingLimitsDuration.month

number

The duration of bookings per month (must be a multiple of 15)

Example:

180

bookingLimitsDuration.year

number

The duration of bookings per year (must be a multiple of 15)

Example:

240

bookingWindow

object

Limit how far in the future this event can be booked

• Option 1
• Option 2
• Option 3
• Option 4

Show child attributes

bookingWindow.type

enum<string>

required

Whether the window should be business days, calendar days or a range of dates

Available options:

businessDays,

calendarDays,

range

bookingWindow.value

number

required

How many business day into the future can this event be booked

Example:

5

bookingWindow.rolling

boolean

  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).

Example:

true

offsetStart

number

Offset timeslots shown to bookers by a specified number of minutes

bookerLayouts

object

Should booker have week, month or column view. Specify default layout and enabled layouts user can pick.

Show child attributes

bookerLayouts.defaultLayout

enum<string>

required

Available options:

month,

week,

column

bookerLayouts.enabledLayouts

enum<string>[]

required

Array of valid layouts - month, week or column

Available options:

month,

week,

column

confirmationPolicy

object

Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.

• Option 1
• Option 2

Show child attributes

confirmationPolicy.type

enum<string>

required

The policy that determines when confirmation is required

Available options:

always,

time

Example:

"always"

confirmationPolicy.blockUnconfirmedBookingsInBooker

boolean

required

Unconfirmed bookings still block calendar slots.

confirmationPolicy.noticeThreshold

object

The notice threshold required before confirmation is needed. Required when type is 'time'.

Show child attributes

confirmationPolicy.noticeThreshold.unit

string

required

The unit of time for the notice threshold (e.g., minutes, hours)

Example:

"minutes"

confirmationPolicy.noticeThreshold.count

number

required

The time value for the notice threshold

Example:

30

recurrence

object

Create a recurring event type.

• Option 1
• Option 2

Show child attributes

recurrence.interval

number

required

Repeats every {count} week | month | year

Example:

10

recurrence.occurrences

number

required

Repeats for a maximum of {count} events

Example:

10

recurrence.frequency

enum<string>

required

Available options:

yearly,

monthly,

weekly

requiresBookerEmailVerification

boolean

hideCalendarNotes

boolean

lockTimeZoneToggleOnBookingPage

boolean

color

object

Show child attributes

color.lightThemeHex

string

required

Color used for event types in light theme

Example:

"#292929"

color.darkThemeHex

string

required

Color used for event types in dark theme

Example:

"#fafafa"

seats

object

Create an event type with multiple seats.

• Option 1
• Option 2

Show child attributes

seats.seatsPerTimeSlot

number

required

Number of seats available per time slot

Example:

4

seats.showAttendeeInfo

boolean

required

Show attendee information to other guests

Example:

true

seats.showAvailabilityCount

boolean

required

Display the count of available seats

Example:

true

customName

string

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}

Example:

"{Event type title} between {Organiser} and {Scheduler}"

destinationCalendar

object

Show child attributes

destinationCalendar.integration

string

required

The integration type of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the integration type of your connected calendars.

destinationCalendar.externalId

string

required

The external ID of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the external IDs of your connected calendars.

useDestinationCalendarEmail

boolean

hideCalendarEventDetails

boolean

successRedirectUrl

string

A valid URL where the booker will redirect to, once the booking is completed successfully

Example:

"https://masterchief.com/argentina/flan/video/9129412"

hosts

object[]

Hosts contain specific team members you want to assign to this event type, but if you want to assign all team members, use assignAllTeamMembers: true instead and omit this field. For platform customers the hosts can include userIds only of managed users.

Show child attributes

hosts.userId

number

required

Which user is the host of this event

hosts.mandatory

boolean

Only relevant for round robin event types. If true then the user must attend round robin event always.

hosts.priority

enum<string>

Available options:

lowest,

low,

medium,

high,

highest

assignAllTeamMembers

boolean

If true, all current and future team members will be assigned to this event type

locations

object[]

Locations where the event will take place. If not provided, cal video link will be used as the location.

• Option 1
• Option 2
• Option 3
• Option 4
• Option 5
• Option 6
• Option 7
• Option 8

Show child attributes

locations.type

string

required

only allowed value for type is address

Example:

"address"

locations.address

string

required

Example:

"123 Example St, City, Country"

locations.public

boolean

required

Response

201 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

required

Show child attributes

data.id

number

required

Example:

1

data.lengthInMinutes

number

required

Required range: x >= 1

Example:

60

data.title

string

required

Example:

"Learn the secrets of masterchief!"

data.slug

string

required

Example:

"learn-the-secrets-of-masterchief"

data.description

string

required

Example:

"Discover the culinary wonders of Argentina by making the best flan ever!"

data.locations

object[]

required

• Option 1
• Option 2
• Option 3
• Option 4
• Option 5
• Option 6

Show child attributes

data.locations.type

enum<string>

required

only allowed value for type is address

Available options:

address,

link,

integration,

phone,

attendeeAddress,

attendeePhone,

attendeeDefined,

organizersDefaultApp

Example:

"address"

data.locations.address

string

required

Example:

"123 Example St, City, Country"

data.locations.public

boolean

required

data.bookingFields

object[]

required

• Option 1
• Option 2
• Option 3
• Option 4
• Option 5
• Option 6
• Option 7
• Option 8
• Option 9
• Option 10
• Option 11
• Option 12
• Option 13
• Option 14
• Option 15
• Option 16
• Option 17
• Option 18
• Option 19

Show child attributes

data.bookingFields.type

enum<string>

default:name

required

only allowed value for type is name. Used for having 1 booking field for both first name and last name.

Available options:

name,

email,

phone,

address,

text,

number,

textarea,

select,

multiselect,

multiemail,

checkbox,

radio,

boolean,

url

Example:

"name"

data.bookingFields.isDefault

object

required

This property is always true because it's a default field

Example:

true

data.bookingFields.slug

string

default:name

required

data.bookingFields.required

boolean

required

data.bookingFields.label

string

data.bookingFields.placeholder

string

data.bookingFields.disableOnPrefill

boolean

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.

data.disableGuests

boolean

required

data.recurrence

object

required

Show child attributes

data.recurrence.interval

number

required

Repeats every {count} week | month | year

Example:

10

data.recurrence.occurrences

number

required

Repeats for a maximum of {count} events

Example:

10

data.recurrence.frequency

enum<string>

required

Available options:

yearly,

monthly,

weekly

data.metadata

object

required

data.price

number

required

data.currency

string

required

data.lockTimeZoneToggleOnBookingPage

boolean

required

data.forwardParamsSuccessRedirect

boolean | null

required

data.successRedirectUrl

string | null

required

data.isInstantEvent

boolean

required

data.scheduleId

number | null

required

data.teamId

number

required

data.hosts

object[]

required

Show child attributes

data.hosts.userId

number

required

Which user is the host of this event

data.hosts.name

string

required

Example:

"John Doe"

data.hosts.mandatory

boolean

default:false

Only relevant for round robin event types. If true then the user must attend round robin event always.

data.hosts.priority

enum<string>

default:medium

Available options:

lowest,

low,

medium,

high,

highest

data.hosts.avatarUrl

string | null

Example:

"https://cal.com/api/avatar/d95949bc-ccb1-400f-acf6-045c51a16856.png"

data.schedulingType

enum<string>

required

Available options:

roundRobin,

collective,

managed

data.team

object

required

Show child attributes

data.team.id

number

required

data.team.slug

string

data.team.bannerUrl

string

data.team.name

string

data.team.logoUrl

string

data.team.weekStart

string

data.team.brandColor

string

data.team.darkBrandColor

string

data.team.theme

string

data.lengthInMinutesOptions

number[]

If you want that user can choose between different lengths of the event you can specify them here. Must include the provided lengthInMinutes.

Example:

[15, 30, 60]

data.slotInterval

number | null

Example:

60

data.minimumBookingNotice

number

Required range: x >= 0

Example:

0

data.beforeEventBuffer

number

Required range: x >= 0

Example:

0

data.afterEventBuffer

number

Required range: x >= 0

Example:

0

data.seatsPerTimeSlot

number | null

data.seatsShowAvailabilityCount

boolean | null

data.bookingLimitsCount

object

data.onlyShowFirstAvailableSlot

boolean

data.bookingLimitsDuration

object

data.bookingWindow

object[]

Limit how far in the future this event can be booked

• Option 1
• Option 2
• Option 3

Show child attributes

data.bookingWindow.type

enum<string>

required

Whether the window should be business days, calendar days or a range of dates

Available options:

businessDays,

calendarDays,

range

data.bookingWindow.value

number

required

How many business day into the future can this event be booked

Example:

5

data.bookingWindow.rolling

boolean

  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).

Example:

true

data.bookerLayouts

object

Show child attributes

data.bookerLayouts.defaultLayout

enum<string>

required

Available options:

month,

week,

column

data.bookerLayouts.enabledLayouts

enum<string>[]

required

Array of valid layouts - month, week or column

Available options:

month,

week,

column

data.confirmationPolicy

object

data.requiresBookerEmailVerification

boolean

data.hideCalendarNotes

boolean

data.color

object

Show child attributes

data.color.lightThemeHex

string

required

Color used for event types in light theme

Example:

"#292929"

data.color.darkThemeHex

string

required

Color used for event types in dark theme

Example:

"#fafafa"

data.seats

object

Show child attributes

data.seats.seatsPerTimeSlot

number

required

Number of seats available per time slot

Example:

4

data.seats.showAttendeeInfo

boolean

required

Show attendee information to other guests

Example:

true

data.seats.showAvailabilityCount

boolean

required

Display the count of available seats

Example:

true

data.offsetStart

number

Required range: x >= 1

data.customName

string

data.destinationCalendar

object

Show child attributes

data.destinationCalendar.integration

string

required

The integration type of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the integration type of your connected calendars.

data.destinationCalendar.externalId

string

required

The external ID of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the external IDs of your connected calendars.

data.useDestinationCalendarEmail

boolean

data.hideCalendarEventDetails

boolean

data.ownerId

number | null

data.parentEventTypeId

number | null

For managed event types, parent event type is the event type that this event type is based on

data.assignAllTeamMembers

boolean