Event types

POSTCreate an event type

Creates a new event type with custom configuration, availability, and settings for the authenticated user or organization.

POST/v2/event-types

POST/v2/event-types

Request Body

application/jsonRequired

lengthInMinutesRequirednumber

lengthInMinutesOptionsarray<string>

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

titleRequiredstring

slugRequiredstring

descriptionstring

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.

disableGuestsboolean

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

slotIntervalnumber

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.

minimumBookingNoticenumber

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

beforeEventBuffernumber

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.

afterEventBuffernumber

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.

scheduleIdnumber

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

bookingLimitsCountobject | object

Limit how many times this event can be booked

bookerActiveBookingsLimitobject | object

Limit the number of active bookings a booker can make for this event type.

onlyShowFirstAvailableSlotboolean

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

bookingLimitsDurationobject | object

Limit total amount of time that this event can be booked

bookingWindowobject | object | object | object

Limit how far in the future this event can be booked

offsetStartnumber

Offset timeslots shown to bookers by a specified number of minutes

bookerLayoutsobject

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

confirmationPolicyobject | object

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

recurrenceobject | object

Create a recurring event type.

requiresBookerEmailVerificationboolean

hideCalendarNotesboolean

lockTimeZoneToggleOnBookingPageboolean

colorobject

seatsobject | object

Create an event type with multiple seats.

customNamestring

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}

destinationCalendarobject

useDestinationCalendarEmailboolean

hideCalendarEventDetailsboolean

successRedirectUrlstring

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

hideOrganizerEmailboolean

Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events

calVideoSettingsobject

Cal video settings for the event type. Platform customers can't manage this property because currently we have no way of determining if managed user is a host or an attendee.

hiddenboolean

bookingRequiresAuthenticationboolean

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.

Default: false

disableCancellingobject

Settings for disabling cancelling of this event type.

disableReschedulingobject

Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.

interfaceLanguagestring

Set preferred language for the booking interface. Use empty string for visitor's browser language (default).

Value in:

"" | "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"

allowReschedulingPastBookingsboolean

Enabling this option allows for past events to be rescheduled.

Default: false

allowReschedulingCancelledBookingsboolean

When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking.

Default: false

showOptimizedSlotsboolean

Arrange time slots to optimize availability.

Default: false

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

Header Parameters

cal-api-versionRequiredstring

Must be set to 2024-06-14. If not set to this value, the endpoint will default to an older version.

Default: "2024-06-14"

AuthorizationRequiredstring

value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token

curl -X POST "https://example.com/v2/event-types" \
  -H "cal-api-version: 2024-06-14" \
  -H "Authorization: <string>" \
  -H "Content-Type: application/json" \
  -d '{
    "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": 0,
    "minimumBookingNotice": 0,
    "beforeEventBuffer": 0,
    "afterEventBuffer": 0,
    "scheduleId": 0,
    "bookingLimitsCount": {
      "day": 1,
      "week": 2,
      "month": 3,
      "year": 4,
      "disabled": false
    },
    "bookerActiveBookingsLimit": {
      "maximumActiveBookings": 3,
      "offerReschedule": true
    },
    "onlyShowFirstAvailableSlot": true,
    "bookingLimitsDuration": {
      "day": 60,
      "week": 120,
      "month": 180,
      "year": 240
    },
    "bookingWindow": {
      "type": "businessDays",
      "value": 5,
      "rolling": true
    },
    "offsetStart": 0,
    "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",
    "hideOrganizerEmail": true,
    "calVideoSettings": {
      "disableRecordingForOrganizer": true,
      "disableRecordingForGuests": true,
      "redirectUrlOnExit": {},
      "enableAutomaticRecordingForOrganizer": true,
      "enableAutomaticTranscription": true,
      "disableTranscriptionForGuests": true,
      "disableTranscriptionForOrganizer": true,
      "sendTranscriptionEmails": true
    },
    "hidden": true,
    "bookingRequiresAuthentication": false,
    "disableCancelling": {
      "disabled": true
    },
    "disableRescheduling": {
      "disabled": false,
      "minutesBefore": 60
    },
    "interfaceLanguage": "",
    "allowReschedulingPastBookings": false,
    "allowReschedulingCancelledBookings": false,
    "showOptimizedSlots": false,
    "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": "name",
        "required": true
      }
    ],
    "disableGuests": true,
    "slotInterval": 60,
    "minimumBookingNotice": 0,
    "beforeEventBuffer": 0,
    "afterEventBuffer": 0,
    "recurrence": {
      "interval": 10,
      "occurrences": 10,
      "frequency": "yearly"
    },
    "metadata": {},
    "price": 0,
    "currency": "string",
    "lockTimeZoneToggleOnBookingPage": true,
    "seatsPerTimeSlot": {},
    "forwardParamsSuccessRedirect": {},
    "successRedirectUrl": {},
    "isInstantEvent": true,
    "seatsShowAvailabilityCount": true,
    "scheduleId": 0,
    "bookingLimitsCount": {},
    "bookerActiveBookingsLimit": {
      "maximumActiveBookings": 3,
      "offerReschedule": true
    },
    "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": 0,
    "customName": "string",
    "destinationCalendar": {
      "integration": "string",
      "externalId": "string"
    },
    "useDestinationCalendarEmail": true,
    "hideCalendarEventDetails": true,
    "hideOrganizerEmail": true,
    "calVideoSettings": {
      "disableRecordingForOrganizer": true,
      "disableRecordingForGuests": true,
      "redirectUrlOnExit": {},
      "enableAutomaticRecordingForOrganizer": true,
      "enableAutomaticTranscription": true,
      "disableTranscriptionForGuests": true,
      "disableTranscriptionForOrganizer": true,
      "sendTranscriptionEmails": true
    },
    "hidden": true,
    "bookingRequiresAuthentication": true,
    "disableCancelling": {
      "disabled": true
    },
    "disableRescheduling": {
      "disabled": true,
      "minutesBefore": 60
    },
    "interfaceLanguage": "string",
    "allowReschedulingPastBookings": true,
    "allowReschedulingCancelledBookings": true,
    "showOptimizedSlots": true,
    "ownerId": 10,
    "users": [
      "string"
    ],
    "bookingUrl": "https://cal.com/john-doe/30min"
  }
}

List Your Conferencing Applications

Get all event types

POSTCreate an event type

Request Body

Header Parameters

Response