> ## Documentation Index
> Fetch the complete documentation index at: https://cal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar invite descriptions

> Configure host and guest descriptions in booking calendar invites.

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:

1. An event-type `custom` template or explicit `standard` mode.
2. The organization default when the event type is set to `inherit`.
3. 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.

```bash theme={null}
curl https://api.cal.com/v2/organizations/ORG_ID/calendar-invites \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash theme={null}
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.

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.