Calendar invite descriptions

Calendar-invite templates let you customize the description guests and hosts receive in calendar invitations. The host and guest versions are configured independently. They apply to the ICS attachments in scheduled booking emails and, when the separate host calendar invite is written, to that invite as well. Event-type responses do not expose either template. Guest descriptions omit booking fields marked hidden. Host descriptions retain those fields.

Resolution and modes

For each audience, Cal.com resolves the description in this order:

An event-type custom template or explicit standard mode.
The organization default when the event type is set to inherit.
Cal.com’s standard calendar description.

Event-type mode	Result
`inherit`	Use the organization default, or the standard description if no default exists.
`standard`	Use the standard description, bypassing the organization default.
`custom`	Use the event type’s custom description.

Organization defaults support inherit (no default; use the standard description) and custom. Managed event types inherit their parent’s invite settings and are read-only. Configure templates on the managed parent. Events without a persisted event type, including dynamic events, use the standard description.

Template variables

Templates use {VARIABLE} placeholders. Supported built-in names include:

Values	Variables
Event location	`{Location}`, `{LOCATION}`
Event type title	`{Link title}`, `{LINK_TITLE}`, `{Event type title}`, `{EVENT_TYPE_TITLE}`
Attendee name	`{Scheduler}`, `{USER}`, `{ATTENDEE}`
Attendee first name	`{Scheduler first name}`, `{ATTENDEE_FIRST_NAME}`
Attendee last name	`{Scheduler last name}`, `{ATTENDEE_LAST_NAME}`
Host name	`{Organiser}`, `{HOST}`, `{ORGANIZER_NAME}`
Host first name	`{Organiser first name}`, `{ORGANIZER_FIRST_NAME}`
Event duration	`{Event duration}`, `{EVENT_DURATION}`
Booking management link	`{MANAGE_LINK}`

Booking form fields can also be referenced by their field slug, case-insensitively (for example, {NOTES}). Guest descriptions do not resolve hidden fields.

Limits and sanitization

Custom templates are limited to 5,000 characters. HTML tags are stripped before saving; Markdown links are preserved. If sanitization leaves a custom template empty, it falls back to inherit when an organization is available and standard otherwise. An organization template that becomes empty falls back to inherit.

API access and organization workflow

Organization defaults follow the organization PBAC rules: the organization.update PBAC permission grants access, or the ORG_ADMIN role applies when PBAC is not granting it. OAuth clients need ORG_PROFILE_READ to read and ORG_PROFILE_WRITE to update. Platform organizations must have the Essentials plan; regular organizations are not subject to platform plan gating.

curl https://api.cal.com/v2/organizations/ORG_ID/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PATCH https://api.cal.com/v2/organizations/ORG_ID/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "host": {
      "mode": "custom",
      "template": "Meeting with {ATTENDEE} about {LINK_TITLE}"
    },
    "guest": {
      "mode": "custom",
      "template": "Join {LINK_TITLE} with {HOST}: {MANAGE_LINK}"
    }
  }'

Team event-type routes are available at /v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/calendar-invites. Personal and team event-type calendar-invite routes use API version 2026-06-12. Access to team routes is the same as updating/reading the team event type (eventType.update / eventType.readTeamEventTypes PBAC permission, or team ADMIN/OWNER role when PBAC is not granting it). OAuth clients need TEAM_EVENT_TYPE_READ or TEAM_EVENT_TYPE_WRITE. The API returns 404 if the event type does not belong to that team.

curl -X PATCH https://api.cal.com/v2/organizations/ORG_ID/teams/TEAM_ID/event-types/123/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "cal-api-version: 2026-06-12" \
  -H "Content-Type: application/json" \
  -d '{ "guest": { "mode": "custom", "template": "Hello {ATTENDEE}" } }'

For a team that is not part of an organization, use /v2/teams/{teamId}/event-types/{eventTypeId}/calendar-invites:

curl https://api.cal.com/v2/teams/TEAM_ID/event-types/123/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "cal-api-version: 2026-06-12"

curl -X PATCH https://api.cal.com/v2/teams/TEAM_ID/event-types/123/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "cal-api-version: 2026-06-12" \
  -H "Content-Type: application/json" \
  -d '{ "guest": { "mode": "custom", "template": "Hello {ATTENDEE}" } }'

Personal event-type routes are GET and PATCH /v2/event-types/{eventTypeId}/calendar-invites. They use the same owner/read authorization and EVENT_TYPE_READ or EVENT_TYPE_WRITE OAuth scope as the corresponding event-type endpoint. A patch changes only the supplied audience.

Platform-managed users

Platform organizations can use a managed-user access token to configure that managed user’s personal event types. For example, override only the host template:

curl -X PATCH https://api.cal.com/v2/event-types/123/calendar-invites \
  -H "Authorization: Bearer MANAGED_USER_ACCESS_TOKEN" \
  -H "cal-api-version: 2026-06-12" \
  -H "Content-Type: application/json" \
  -d '{ "host": { "mode": "custom", "template": "Host: {ATTENDEE}" } }'

You can provide the write-only calendarInvites field when creating or updating a personal or team event type using either API version 2026-06-12 or 2024-06-14. For example:

curl -X POST https://api.cal.com/v2/event-types \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "cal-api-version: 2026-06-12" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product consultation",
    "slug": "product-consultation",
    "lengthInMinutes": 30,
    "calendarInvites": {
      "host": { "mode": "custom", "template": "Host: {ATTENDEE}" }
    }
  }'

For integrations using API version 2024-06-14, the same calendarInvites field is accepted on personal and team event-type create/update requests when the request includes cal-api-version: 2024-06-14. The field is write-only: templates are read using the dedicated calendar-invites endpoints, not from GET /v2/event-types or the public event-type listing. To read the effective personal settings, including the organization default, use:

curl https://api.cal.com/v2/event-types/123/calendar-invites \
  -H "Authorization: Bearer MANAGED_USER_ACCESS_TOKEN" \
  -H "cal-api-version: 2026-06-12"

Read team and organization settings from their corresponding calendar-invites routes:

curl https://api.cal.com/v2/organizations/ORG_ID/teams/TEAM_ID/event-types/123/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "cal-api-version: 2026-06-12"

curl https://api.cal.com/v2/teams/TEAM_ID/event-types/123/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "cal-api-version: 2026-06-12"

curl https://api.cal.com/v2/organizations/ORG_ID/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Status	Meaning
`400`	Invalid template, template longer than 5,000 characters, missing host/guest input, or attempt to update a managed child.
`401`	Missing or invalid authentication.
`403`	Authenticated caller lacks the required role, PBAC permission, OAuth scope, or applicable platform-plan access.
`404`	Event type or organization does not exist or is not accessible; team event type does not belong to the requested team.

Getting Started

CORE

CALENDARS

EVENT TYPES & AUTOMATION

TEAMS

ORGANIZATIONS

AUTH & ACCESS

DEPRECATED

Calendar invite descriptions

Resolution and modes

Template variables

Limits and sanitization

API access and organization workflow

Platform-managed users

Errors

​Resolution and modes

​Template variables

​Limits and sanitization

​API access and organization workflow

​Platform-managed users

​Errors

Resolution and modes

Template variables

Limits and sanitization

API access and organization workflow

Platform-managed users

Errors