{ "openapi": "3.0.0", "paths": { "/v2/organizations/{orgId}/attributes": { "get": { "description": "Required membership role: `org member`. PBAC permission: `organization.attributes.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesController_getOrganizationAttributes", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganizationAttributesOutput" } } } } }, "summary": "Get all attributes", "tags": ["Orgs / Attributes"], "x-mcp": { "name": "get_org_attributes", "guidance": "List all attributes defined for an organization. Attributes are custom fields (TEXT, NUMBER, SINGLE_SELECT, MULTI_SELECT) used to tag members for routing and round-robin. Supports pagination with skip/take." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesController_createOrganizationAttribute", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationAttributeInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationAttributesOutput" } } } } }, "summary": "Create an attribute", "tags": ["Orgs / Attributes"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/{attributeId}": { "get": { "description": "Required membership role: `org member`. PBAC permission: `organization.attributes.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesController_getOrganizationAttribute", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSingleAttributeOutput" } } } } }, "summary": "Get an attribute", "tags": ["Orgs / Attributes"], "x-mcp": { "name": "get_org_attribute", "guidance": "Get a single organization attribute by ID. Use get_org_attributes to find attribute IDs and get_attribute_options to list available options." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesController_updateOrganizationAttribute", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationAttributeInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationAttributesOutput" } } } } }, "summary": "Update an attribute", "tags": ["Orgs / Attributes"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesController_deleteOrganizationAttribute", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOrganizationAttributesOutput" } } } } }, "summary": "Delete an attribute", "tags": ["Orgs / Attributes"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/{attributeId}/options": { "post": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_createOrganizationAttributeOption", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationAttributeOptionInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttributeOptionOutput" } } } } }, "summary": "Create an attribute option", "tags": ["Orgs / Attributes / Options"], "x-platform-plan": "ESSENTIALS" }, "get": { "description": "Required membership role: `org member`. PBAC permission: `organization.attributes.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeOptions", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllAttributeOptionOutput" } } } } }, "summary": "Get all attribute options", "tags": ["Orgs / Attributes / Options"], "x-mcp": { "name": "get_attribute_options", "guidance": "List all available options for a SINGLE_SELECT or MULTI_SELECT attribute. Returns option IDs and values needed when assigning attributes to users via assign_attribute_to_user." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/{attributeId}/options/{optionId}": { "delete": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_deleteOrganizationAttributeOption", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "optionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAttributeOptionOutput" } } } } }, "summary": "Delete an attribute option", "tags": ["Orgs / Attributes / Options"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_updateOrganizationAttributeOption", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "optionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationAttributeOptionInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAttributeOptionOutput" } } } } }, "summary": "Update an attribute option", "tags": ["Orgs / Attributes / Options"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/{attributeId}/options/assigned": { "get": { "description": "Required membership role: `org member`. PBAC permission: `organization.attributes.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptions", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of responses to skip", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of responses to take", "schema": { "type": "number" } }, { "name": "assignedOptionIds", "required": false, "in": "query", "description": "Filter by assigned attribute option ids. ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?assignedOptionIds=aaaaaaaa-bbbb-cccc-dddd-eeeeee1eee,aaaaaaaa-bbbb-cccc-dddd-eeeeee2eee", "type": "array", "items": { "type": "string" } } }, { "name": "teamIds", "required": false, "in": "query", "description": "Filter by teamIds. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=100,200", "type": "array", "items": { "type": "number" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllAttributeAssignedOptionOutput" } } } } }, "summary": "Get all assigned attribute options by attribute ID", "tags": ["Orgs / Attributes / Options"], "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/slugs/{attributeSlug}/options/assigned": { "get": { "description": "Required membership role: `org member`. PBAC permission: `organization.attributes.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptionsBySlug", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeSlug", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of responses to skip", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of responses to take", "schema": { "type": "number" } }, { "name": "assignedOptionIds", "required": false, "in": "query", "description": "Filter by assigned attribute option ids. ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?assignedOptionIds=aaaaaaaa-bbbb-cccc-dddd-eeeeee1eee,aaaaaaaa-bbbb-cccc-dddd-eeeeee2eee", "type": "array", "items": { "type": "string" } } }, { "name": "teamIds", "required": false, "in": "query", "description": "Filter by teamIds. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=100,200", "type": "array", "items": { "type": "number" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllAttributeAssignedOptionOutput" } } } } }, "summary": "Get all assigned attribute options by attribute slug", "tags": ["Orgs / Attributes / Options"], "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/options/{userId}": { "post": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.editUsers`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_assignOrganizationAttributeOptionToUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignOrganizationAttributeOptionToUserInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignOptionUserOutput" } } } } }, "summary": "Assign an attribute to a user", "tags": ["Orgs / Attributes / Options"], "x-mcp": { "name": "assign_attribute_to_user", "guidance": "Assign an attribute option to a user. For SINGLE_SELECT/MULTI_SELECT attributes, pass attributeOptionId (use get_attribute_options to list available options). For TEXT/NUMBER attributes, pass value instead to create an option on the fly. Optionally set a weight for round-robin routing." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_WRITE"], "x-platform-plan": "ESSENTIALS" }, "get": { "description": "Required membership role: `org member`. PBAC permission: `organization.attributes.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeOptionsForUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOptionUserOutput" } } } } }, "summary": "Get all attribute options for a user", "tags": ["Orgs / Attributes / Options"], "x-mcp": { "name": "get_user_attributes", "guidance": "Get all attribute options assigned to a specific user within an organization. Returns grouped attributes with their assigned option values and weights." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/options/{userId}/{attributeOptionId}": { "patch": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.editUsers`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_updateOrganizationAttributeOptionForUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeOptionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationAttributeOptionUserInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOptionUserOutput" } } } } }, "summary": "Update an attribute assignment for a user", "tags": ["Orgs / Attributes / Options"], "x-mcp": { "name": "update_user_attribute", "guidance": "Update an existing attribute assignment for a user (e.g. change the weight). Use get_user_attributes to find the attributeOptionId." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_WRITE"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.editUsers`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_unassignOrganizationAttributeOptionFromUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "attributeOptionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnassignOptionUserOutput" } } } } }, "summary": "Unassign an attribute from a user", "tags": ["Orgs / Attributes / Options"], "x-mcp": { "name": "unassign_attribute_from_user", "guidance": "Remove an attribute option assignment from a user. Use get_user_attributes to find the attributeOptionId. Confirm with the user before proceeding." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/assignments/{userId}/history": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `organization.attributes.readAuditLogs`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignmentHistory", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of audit log entries to return.", "schema": { "minimum": 1, "maximum": 50, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous response.", "schema": { "format": "uuid", "example": "018ff5cd-6dc4-7d57-bcbc-374702ca8b38", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAttributeAssignmentHistoryOutput" } } } } }, "summary": "Get attribute assignment history for a user", "tags": ["Orgs / Attributes / Options"], "x-mcp": { "name": "get_user_attribute_history", "guidance": "Get the attribute assignment history (audit log) for a user within an organization. Returns a chronological log of attribute assignment changes (assigned, updated, unassigned). Supports pagination with limit (1-50) and cursor. Requires org admin role." }, "x-oauth-scopes": ["ORG_ATTRIBUTES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/sync-history": { "get": { "description": "Returns a paginated list of integration sync runs for the organization, including rule evaluations, applied field mappings, and team membership changes per run. Supports cursor-based pagination.", "operationId": "OrganizationAttributeSyncHistoryController_getAttributeSyncHistory", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return (1–100)", "schema": { "minimum": 1, "maximum": 100, "default": 25, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for keyset pagination (UUID of the last item from previous page)", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAttributeSyncHistoryOutput" } } } } }, "summary": "Get attribute sync history", "tags": ["Orgs / Attributes / Sync History"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/attributes/sync-history/user/{userId}": { "get": { "description": "Returns a paginated list of integration sync runs filtered by user within the organization, including rule evaluations, applied field mappings, and team membership changes per run. Supports cursor-based pagination.", "operationId": "OrganizationAttributeSyncHistoryController_getUserSyncHistory", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return (1–100)", "schema": { "minimum": 1, "maximum": 100, "default": 25, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for keyset pagination (UUID of the last item from previous page)", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAttributeSyncHistoryOutput" } } } } }, "summary": "Get sync history for a specific user", "tags": ["Orgs / Attributes / Sync History"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/bookings": { "get": { "description": "Cursor-paginated org bookings listing. Pass the `pagination.nextCursor` from the previous response as the `cursor` query parameter to fetch the next page. Omit `cursor` to fetch the first page. `pagination.hasMore` is `false` and `pagination.nextCursor` is `null` when you've reached the last page.\n\nMust pass `cal-api-version: 2026-05-01` header.\n\n**`status` filters to a single status.** Pass one (e.g. `?status=upcoming`) or omit to walk all statuses. To list bookings across multiple statuses, issue parallel requests — one per status — and merge client-side.\n\nRequired membership role: `org admin`. PBAC permission: `booking.readOrgBookings`. If accessed using an OAuth access token, the `ORG_BOOKING_READ` scope is required.\n\nFor managed organizations, bookings where the managed organization owner is the organizer or an attendee are excluded from the result.", "operationId": "OrganizationsBookingsController_getAllOrgTeamBookingsCursor", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter bookings by a single status. Pass one (e.g. `?status=upcoming`) or omit to walk all statuses ordered by `Booking.uuid DESC`. To list bookings across multiple statuses, issue parallel requests, one per status.", "schema": { "example": "upcoming", "type": "string", "enum": ["upcoming", "recurring", "past", "cancelled", "unconfirmed"] } }, { "name": "attendeeEmail", "required": false, "in": "query", "description": "Filter bookings by the attendee's email address.", "schema": { "example": "example@domain.com", "type": "string" } }, { "name": "attendeeName", "required": false, "in": "query", "description": "Filter bookings by the attendee's name.", "schema": { "example": "John Doe", "type": "string" } }, { "name": "bookingUid", "required": false, "in": "query", "description": "Filter bookings by the booking Uid.", "schema": { "example": "2NtaeaVcKfpmSZ4CthFdfk", "type": "string" } }, { "name": "eventTypeIds", "required": false, "in": "query", "description": "Filter bookings by event type ids. Event type ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?eventTypeIds=100,200", "type": "string" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter bookings by event type id.", "schema": { "example": "?eventTypeId=100", "type": "string" } }, { "name": "teamsIds", "required": false, "in": "query", "description": "Filter bookings by team ids that user is part of. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=50,60", "type": "string" } }, { "name": "teamId", "required": false, "in": "query", "description": "Filter bookings by team id that user is part of", "schema": { "example": "?teamId=50", "type": "string" } }, { "name": "afterStart", "required": false, "in": "query", "description": "Filter bookings with start after this date string.", "schema": { "example": "?afterStart=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeEnd", "required": false, "in": "query", "description": "Filter bookings with end before this date string.", "schema": { "example": "?beforeEnd=2025-03-07T11:00:00.000Z", "type": "string" } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created after this date string.", "schema": { "example": "?afterCreatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created before this date string.", "schema": { "example": "?beforeCreatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated after this date string.", "schema": { "example": "?afterUpdatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated before this date string.", "schema": { "example": "?beforeUpdatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortCreated", "required": false, "in": "query", "description": "Sort results by their creation time (when booking was made) in ascending or descending order.", "schema": { "example": "?sortCreated=asc OR ?sortCreated=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort results by their updated time (for example when booking status changes) in ascending or descending order.", "schema": { "example": "?sortUpdatedAt=asc OR ?sortUpdatedAt=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "example": "eyJ2IjoxLCJzb3J0VXVpZCI6IjAxOGY0YzJlLTNmMWEtN2FiYy05ZGVmLTAxMjM0NTY3ODlhYiJ9", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "userIds", "required": false, "in": "query", "description": "Filter bookings by ids of users within your organization.", "schema": { "minItems": 1, "example": "?userIds=100,200", "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingsOutput_2026_05_01" } } } } }, "summary": "Get organization bookings (cursor pagination)", "tags": ["Orgs / Bookings"], "x-oauth-scopes": ["ORG_BOOKING_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/bookings/report": { "post": { "description": "Report a booking within the organization. A booking report is created and the reported booking along with other matching upcoming bookings are silently cancelled. If accessed using an OAuth access token, the `ORG_BOOKING_WRITE` scope is required.", "operationId": "OrganizationsBookingsController_reportOrgBooking", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOrgBookingInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOrgBookingOutput" } } } } }, "summary": "Report an organization booking", "tags": ["Orgs / Bookings"], "x-oauth-scopes": ["ORG_BOOKING_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/bookings/block": { "post": { "description": "Add the email or domain of a booking attendee to the organization blocklist. All matching upcoming bookings in the organization are silently cancelled. If accessed using an OAuth access token, the `ORG_BOOKING_WRITE` scope is required.", "operationId": "OrganizationsBookingsController_blockOrgBooking", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockOrgBookingInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockOrgBookingOutput" } } } } }, "summary": "Block an organization booking attendee", "tags": ["Orgs / Bookings"], "x-oauth-scopes": ["ORG_BOOKING_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/calendar-invites": { "get": { "description": "Returns the host and guest organization defaults used when an event type inherits its calendar-invite description. Access matches the web organization procedure: the `organization.update` PBAC permission grants access, or the ORG_ADMIN role applies when PBAC is not granting it. OAuth clients require `ORG_PROFILE_READ`. Custom templates are limited to 5,000 characters. Platform organizations must have the Essentials plan; regular organizations are not subject to platform plan gating. An `inherit` mode uses Cal.com's standard invite description.", "operationId": "OrganizationsCalendarInvitesController_getOrganizationCalendarInvites", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCalendarInvitesOutput" } } } } }, "summary": "Get organization calendar-invite defaults", "tags": ["Orgs / Calendar Invites"], "x-oauth-scopes": ["ORG_PROFILE_READ"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Updates one or both host and guest organization defaults; omitted audiences are unchanged. Access matches the web organization procedure: the `organization.update` PBAC permission grants access, or the ORG_ADMIN role applies when PBAC is not granting it. OAuth clients require `ORG_PROFILE_WRITE`. Platform organizations must have the Essentials plan; regular organizations are not subject to platform plan gating. `custom` templates are limited to 5,000 characters and sanitized before saving; Markdown links are preserved. An `inherit` mode clears the organization default. Event types resolve their own custom template first, then this default, then Cal.com's standard description.", "operationId": "OrganizationsCalendarInvitesController_updateOrganizationCalendarInvites", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCalendarInvitesInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCalendarInvitesOutput" } } } } }, "summary": "Update organization calendar-invite defaults", "tags": ["Orgs / Calendar Invites"], "x-oauth-scopes": ["ORG_PROFILE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/delegation-credentials": { "get": { "description": "Optionally filter by `domain` to look up the delegation credential configured for a specific domain. Required membership role: `org admin`. PBAC permission: `organization.readDelegationCredentials`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_getDelegationCredentials", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "The unique identifier of the organization whose delegation credentials are returned", "schema": { "example": 123, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "domain", "required": false, "in": "query", "description": "Filter by the domain the delegation credential is configured for", "schema": { "example": "example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDelegationCredentialsOutput" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UnauthorizedException" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "The authenticated user is not an org admin, lacks the `organization.readDelegationCredentials` permission, or the organization is not on the required plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ForbiddenException" }, "message": { "type": "string" } } } } } } } } }, "summary": "Get all delegation credentials of your organization", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_createDelegationCredential", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateGoogleDelegationCredentialInput" }, { "$ref": "#/components/schemas/CreateMicrosoftDelegationCredentialInput" } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDelegationCredentialOutput" } } } } }, "summary": "Save delegation credentials for your organization", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/delegation-credentials/{credentialId}": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `organization.readDelegationCredentials`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_getDelegationCredential", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "The unique identifier of the organization the delegation credential belongs to", "schema": { "example": 123, "type": "number" } }, { "name": "credentialId", "required": true, "in": "path", "description": "The unique identifier of the delegation credential", "schema": { "example": "clsx1234567890", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDelegationCredentialOutput" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UnauthorizedException" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "The authenticated user is not an org admin, lacks the `organization.readDelegationCredentials` permission, or the organization is not on the required plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ForbiddenException" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "No delegation credential with the given id exists in the organization, or it belongs to a different organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "NotFoundException" }, "message": { "type": "string" } } } } } } } } }, "summary": "Get a delegation credential of your organization", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_updateDelegationCredential", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "credentialId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDelegationCredentialInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDelegationCredentialOutput" } } } } }, "summary": "Update delegation credentials of your organization", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_deleteDelegationCredential", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "credentialId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDelegationCredentialOutput" } } } } }, "summary": "Delete delegation credentials of your organization", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/delegation-credentials/{credentialId}/reset-rotation": { "post": { "description": "Clears the terminal secret-rotation failure state so managed secret rotation resumes normally. Use this after fixing whatever external configuration issues caused rotation to reach a terminal state. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_resetDelegationCredentialRotation", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "The unique identifier of the organization the delegation credential belongs to", "schema": { "example": 123, "type": "number" } }, { "name": "credentialId", "required": true, "in": "path", "description": "The unique identifier of the delegation credential", "schema": { "example": "clsx1234567890", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetDelegationCredentialRotationOutput" } } } }, "400": { "description": "The delegation credential is not a Microsoft/office365 delegation credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "BadRequestException" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UnauthorizedException" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "The authenticated user is not an org admin, lacks the `organization.update` permission, or the organization is not on the required plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ForbiddenException" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "No delegation credential with the given id exists in the organization, or it belongs to a different organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "NotFoundException" }, "message": { "type": "string" } } } } } } } } }, "summary": "Reset a blocked delegation credential's secret rotation state", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/delegation-credentials/{credentialId}/verify": { "post": { "description": "Runs the same Google Workspace / Microsoft 365 check as enabling the credential, impersonating the authenticated user, without changing the credential. Works whether or not the credential is enabled. A failed check is returned as `verified: false` with the reason, not as an error. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsDelegationCredentialController_verifyDelegationCredential", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "The unique identifier of the organization the delegation credential belongs to", "schema": { "example": 123, "type": "number" } }, { "name": "credentialId", "required": true, "in": "path", "description": "The unique identifier of the delegation credential", "schema": { "example": "clsx1234567890", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDelegationCredentialOutput" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/verify" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UnauthorizedException" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "The authenticated user is not an org admin, lacks the `organization.update` permission, or the organization is not on the required plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/verify" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ForbiddenException" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "No delegation credential with the given id exists in the organization, or it belongs to a different organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "timestamp": { "type": "string", "example": "2024-04-01T00:00:00.000Z" }, "path": { "type": "string", "example": "/v2/organizations/123/delegation-credentials/clsx1234567890/verify" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "NotFoundException" }, "message": { "type": "string" } } } } } } } } }, "summary": "Verify a delegation credential's workspace setup", "tags": ["Orgs / Delegation Credentials"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/memberships": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `organization.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_READ` scope is required.", "operationId": "OrganizationsMembershipsController_getAllMemberships", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "userIds", "required": false, "in": "query", "description": "Filter organization memberships by user ids. If you want to filter by multiple users, separate them with a comma (max 20 user ids).", "schema": { "minItems": 1, "maxItems": 20, "example": "?userIds=100,200", "type": "array", "items": { "type": "number", "maximum": 2147483647, "minimum": 1 } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllOrgMemberships" } } } } }, "summary": "Get all memberships", "tags": ["Orgs / Memberships"], "x-mcp": { "name": "get_org_memberships", "guidance": "List all memberships in an organization. Supports pagination with take/skip (take max 250) and filtering by up to 20 user ids." }, "x-oauth-scopes": ["ORG_MEMBERSHIP_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `organization.invite`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_WRITE` scope is required.\n\nTwo identifier modes are accepted in the request body:\n\n1. **`userId`** — attach an existing user (by id) directly. Use when the caller already knows the Cal.com user id and just needs the membership row created/updated. No notification email is sent. When `accepted: true` takes effect, the user's organization profile is also created, as accepting an invite in the dashboard does, so the user can be added to the organization's teams.\n\n2. **`email`** — invite an existing Cal.com user (by email). Runs the same invite flow the dashboard uses; the user must already exist (if not, the request returns `404` — create them first via `POST /v2/organizations/{orgId}/users`). What happens next depends on the organization's settings:\n\n - **Auto-attach path.** When the organization is verified by Cal.com and the invitee's email domain matches the organization's configured auto-accept domain (both set by Cal.com during organization verification — not editable by the organization's own admins), the user is added as an accepted member: their organization profile is created, the membership is created with `accepted: true`, and they receive a \"you've been added to the organization\" notification email.\n\n - **Pending-invite path.** If either condition is not met, the user receives an \"accept your invite\" notification email and the membership is created with `accepted: false` until they accept it via the dashboard. No organization profile is created until acceptance.\n\n Either way the response's `accepted` value reflects the outcome, seat addition is recorded, and the new seat count is pushed to the billing provider.", "operationId": "OrganizationsMembershipsController_createMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "description": "Either `userId` to attach an existing org user directly, or `email` to invite an existing Cal.com user via the dashboard's invite flow.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Member by User ID", "$ref": "#/components/schemas/CreateOrgMembershipDto" }, { "title": "Member by Email", "$ref": "#/components/schemas/CreateOrgMembershipByEmailDto" } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgMembershipOutput" } } } } }, "summary": "Create a membership", "tags": ["Orgs / Memberships"], "x-oauth-scopes": ["ORG_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/memberships/{membershipId}": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `organization.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_READ` scope is required.", "operationId": "OrganizationsMembershipsController_getOrgMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgMembership" } } } } }, "summary": "Get a membership", "tags": ["Orgs / Memberships"], "x-mcp": { "name": "get_org_membership", "guidance": "Get a specific organization membership by its numeric ID." }, "x-oauth-scopes": ["ORG_MEMBERSHIP_READ"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `organization.remove`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsMembershipsController_deleteMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOrgMembership" } } } } }, "summary": "Delete a membership", "tags": ["Orgs / Memberships"], "x-mcp": { "name": "delete_org_membership", "guidance": "Remove a membership from an organization. This action is irreversible — confirm with the user before proceeding." }, "x-oauth-scopes": ["ORG_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `organization.changeMemberRole`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsMembershipsController_updateMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgMembershipDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgMembership" } } } } }, "summary": "Update a membership", "tags": ["Orgs / Memberships"], "x-mcp": { "name": "update_org_membership", "guidance": "Update an organization membership. Can change role, accepted status, or impersonation settings." }, "x-oauth-scopes": ["ORG_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/roles": { "post": { "description": "Required membership role: `org admin`. PBAC permission: `role.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesController_createRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRoleInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRoleOutput" } } } } }, "summary": "Create a new organization role", "tags": ["Orgs / Roles"], "x-platform-plan": "SCALE" }, "get": { "description": "Required membership role: `org admin`. PBAC permission: `role.readOrgRoles`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesController_getAllRoles", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllOrgRolesOutput" } } } } }, "summary": "Get all organization roles", "tags": ["Orgs / Roles"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/roles/{roleId}": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `role.readOrgRoles`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesController_getRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgRoleOutput" } } } } }, "summary": "Get a specific organization role", "tags": ["Orgs / Roles"], "x-platform-plan": "SCALE" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `role.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesController_updateRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgRoleInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgRoleOutput" } } } } }, "summary": "Update an organization role", "tags": ["Orgs / Roles"], "x-platform-plan": "SCALE" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `role.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesController_deleteRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOrgRoleOutput" } } } } }, "summary": "Delete an organization role", "tags": ["Orgs / Roles"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/roles/{roleId}/permissions": { "post": { "description": "Required membership role: `org admin`. PBAC permission: `role.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesPermissionsController_addPermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRolePermissionsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgRolePermissionsOutput" } } } } }, "summary": "Add permissions to an organization role (single or batch)", "tags": ["Orgs / Roles / Permissions"], "x-platform-plan": "SCALE" }, "get": { "description": "Required membership role: `org admin`. PBAC permission: `role.readOrgRoles`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesPermissionsController_listPermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgRolePermissionsOutput" } } } } }, "summary": "List permissions for an organization role", "tags": ["Orgs / Roles / Permissions"], "x-platform-plan": "SCALE" }, "put": { "description": "Required membership role: `org admin`. PBAC permission: `role.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesPermissionsController_setPermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRolePermissionsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgRolePermissionsOutput" } } } } }, "summary": "Replace all permissions for an organization role", "tags": ["Orgs / Roles / Permissions"], "x-platform-plan": "SCALE" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `role.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesPermissionsController_removePermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "permissions", "required": false, "in": "query", "description": "Permissions to remove (format: resource.action). Supports comma-separated values as well as repeated query params.", "schema": { "example": "?permissions=eventType.read,booking.read", "type": "array", "items": { "type": "string", "enum": [ "*.*", "role.create", "role.read", "role.readTeamRoles", "role.readOrgRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.readOrgEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.create", "team.read", "team.readOrgTeams", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "organization.create", "organization.read", "organization.readMemberships", "organization.readManagedOrganizations", "organization.readDelegationCredentials", "organization.listMembers", "organization.listMembersPrivate", "organization.readMemberAuditLogs", "organization.invite", "organization.remove", "organization.manageBilling", "organization.changeMemberRole", "organization.impersonate", "organization.passwordReset", "organization.editUsers", "organization.update", "organization.delete", "booking.read", "booking.readOrgBookings", "booking.readRecordings", "booking.update", "booking.updateOrgBookings", "booking.reassignOrgPastBookings", "booking.readOrgAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "organization.attributes.read", "organization.attributes.update", "organization.attributes.delete", "organization.attributes.create", "organization.attributes.readSyncHistory", "organization.attributes.editUsers", "organization.attributes.readAuditLogs", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.readOrgRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readOrgAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.readOrgWebhooks", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.readOrgAvailability", "availability.updateTeamAvailability", "availability.updateOrgAvailability", "availability.readOrgAuditLogs", "ooo.readOrgOoo", "watchlist.create", "watchlist.read", "watchlist.update", "watchlist.delete", "featureOptIn.read", "featureOptIn.update", "organization.customDomain.create", "organization.customDomain.read", "organization.customDomain.update", "organization.customDomain.delete", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] } } } ], "responses": { "204": { "description": "" } }, "summary": "Remove multiple permissions from an organization role", "tags": ["Orgs / Roles / Permissions"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/roles/{roleId}/permissions/{permission}": { "delete": { "description": "Required membership role: `org admin`. PBAC permission: `role.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsRolesPermissionsController_removePermission", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "permission", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "summary": "Remove a permission from an organization role", "tags": ["Orgs / Roles / Permissions"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/routing-forms": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `routingForm.readOrgRoutingForms`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_READ` scope is required.", "operationId": "OrganizationsRoutingFormsController_getOrganizationRoutingForms", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of responses to skip", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of responses to take", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort by creation time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort by update time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter by responses created before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter by responses updated before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "routedToBookingUid", "required": false, "in": "query", "description": "Filter by responses routed to a specific booking", "schema": { "type": "string" } }, { "name": "teamIds", "required": false, "in": "query", "description": "Filter by teamIds. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=100,200", "type": "array", "items": { "type": "number" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormsOutput" } } } } }, "summary": "Get organization routing forms", "tags": ["Orgs / Routing forms"], "x-mcp": { "name": "get_org_routing_forms", "guidance": "List routing forms for an organization. Supports filtering by team IDs, date ranges, routed booking UID, and sorting." }, "x-oauth-scopes": ["ORG_ROUTING_FORM_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/routing-forms/{routingFormId}/responses": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `routingForm.readResponsePii`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_READ` scope is required.", "operationId": "OrganizationsRoutingFormsResponsesController_getRoutingFormResponses", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of responses to skip", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of responses to take", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort by creation time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort by update time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter by responses created before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter by responses updated before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "routedToBookingUid", "required": false, "in": "query", "description": "Filter by responses routed to a specific booking", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormResponsesOutput" } } } } }, "summary": "Get routing form responses", "tags": ["Orgs / Routing forms"], "x-mcp": { "name": "get_org_routing_form_responses", "guidance": "Get responses for a specific routing form. Supports filtering by date ranges, routed booking UID, and sorting." }, "x-oauth-scopes": ["ORG_ROUTING_FORM_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `routingForm.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_WRITE` scope is required.", "operationId": "OrganizationsRoutingFormsResponsesController_createRoutingFormResponse", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "start", "required": true, "in": "query", "description": "\n Time starting from which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to start of day or specify hours:\n 2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z\n ", "schema": { "example": "2033-09-05", "type": "string" } }, { "name": "end", "required": true, "in": "query", "description": "\n Time until which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to end of day or specify hours:\n 2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z", "schema": { "example": "2033-09-06", "type": "string" } }, { "name": "timeZone", "required": false, "in": "query", "description": "Time zone in which the available slots should be returned. Defaults to UTC.", "schema": { "example": "Europe/Rome", "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "If event type has multiple possible durations then you can specify the desired duration here. Also, if you are fetching slots for a dynamic event then you can specify the duration her which defaults to 30, meaning that returned slots will be each 30 minutes long.", "schema": { "example": "60", "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Format of slot times in response. Use 'range' to get start and end times.", "schema": { "example": "range", "type": "string", "enum": ["range", "time"] } }, { "name": "bookingUidToReschedule", "required": false, "in": "query", "description": "The unique identifier of the booking being rescheduled. When provided will ensure that the original booking time appears within the returned available slots when rescheduling.", "schema": { "example": "abc123def456", "type": "string" } }, { "name": "rescheduleWithSameHost", "required": false, "in": "query", "description": "Only for round robin event types that allow the person rescheduling to choose the host. True returns slots of the original host, false returns slots of any available host. Ignored for other event types.", "schema": { "example": true, "type": "boolean" } }, { "name": "queueResponse", "required": false, "in": "query", "description": "Whether to queue the form response.", "schema": { "example": true, "type": "boolean" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingFormResponseOutput" } } } } }, "summary": "Create routing form response and get available slots", "tags": ["Orgs / Routing forms"], "x-oauth-scopes": ["ORG_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/routing-forms/{routingFormId}/responses/{responseId}": { "patch": { "description": "Required membership role: `org admin`. PBAC permission: `routingForm.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_WRITE` scope is required.", "operationId": "OrganizationsRoutingFormsResponsesController_updateRoutingFormResponse", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "responseId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingFormResponseInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingFormResponseOutput" } } } } }, "summary": "Update routing form response", "tags": ["Orgs / Routing forms"], "x-oauth-scopes": ["ORG_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/schedules": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `availability.readOrgAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsSchedulesController_getOrganizationSchedules", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulesOutput_2024_06_11" } } } } }, "summary": "Get all schedules", "tags": ["Orgs / Schedules"], "x-oauth-scopes": ["ORG_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/secondary-domains": { "get": { "description": "For platform, the plan must be 'ESSENTIALS' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsSecondaryDomainsController_getSecondaryDomains", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSecondaryDomainsResponseOutput" } } } } }, "summary": "Get all secondary domains of an organization", "tags": ["Orgs / Secondary Domains"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Adds an unverified secondary domain. Publish the returned `verificationRecord` as a DNS TXT record and call the verify endpoint. Once verified, members with this email domain join the organization with usernames suffixed by `usernameSuffix` (e.g. john@acme.fr becomes john-fr). For platform, the plan must be 'ESSENTIALS' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsSecondaryDomainsController_createSecondaryDomain", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationSecondaryDomainInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSecondaryDomainResponseOutput" } } } } }, "summary": "Add a secondary domain to an organization", "tags": ["Orgs / Secondary Domains"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/secondary-domains/{domainId}": { "get": { "description": "For platform, the plan must be 'ESSENTIALS' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsSecondaryDomainsController_getSecondaryDomain", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "domainId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSecondaryDomainResponseOutput" } } } } }, "summary": "Get a secondary domain of an organization", "tags": ["Orgs / Secondary Domains"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "For platform, the plan must be 'ESSENTIALS' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsSecondaryDomainsController_deleteSecondaryDomain", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "domainId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSecondaryDomainResponseOutput" } } } } }, "summary": "Remove a secondary domain from an organization", "tags": ["Orgs / Secondary Domains"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/secondary-domains/{domainId}/verify": { "post": { "description": "Checks the DNS TXT record returned in `verificationRecord` and marks the domain as verified. For platform, the plan must be 'ESSENTIALS' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsSecondaryDomainsController_verifySecondaryDomain", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "domainId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSecondaryDomainResponseOutput" } } } } }, "summary": "Verify a secondary domain of an organization", "tags": ["Orgs / Secondary Domains"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `team.readOrgTeams`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_PROFILE_READ` scope is required.", "operationId": "OrganizationsTeamsController_getAllTeams", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamsOutputResponseDto" } } } } }, "summary": "Get all teams", "tags": ["Orgs / Teams"], "x-mcp": { "name": "get_org_teams", "guidance": "List all teams in an organization. Supports take/skip pagination (take max 250). Requires ORG_ADMIN role. Use get_me to obtain your organizationId. Returns team IDs, names, and slugs needed by other team-scoped tools. If this fails with 403, use get_my_teams instead." }, "x-oauth-scopes": ["ORG_PROFILE_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `team.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_PROFILE_WRITE` scope is required.", "operationId": "OrganizationsTeamsController_createTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgTeamDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamOutputResponseDto" } } } } }, "summary": "Create a team", "tags": ["Orgs / Teams"], "x-oauth-scopes": ["ORG_PROFILE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/me": { "get": { "description": "Required membership role: `org member`. PBAC permission: `team.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_READ` scope is required.", "operationId": "OrganizationsTeamsController_getMyTeams", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMeTeamsOutputResponseDto" } } } } }, "summary": "Get teams membership for user", "tags": ["Orgs / Teams"], "x-mcp": { "name": "get_my_teams", "guidance": "List teams the authenticated user belongs to. Supports take/skip pagination (take max 250). Works for any org member (org admins see all teams). Use get_me to obtain your organizationId. Returns team IDs, names, and slugs needed by other team-scoped tools." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readTeamSettings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_READ` scope is required.", "operationId": "OrganizationsTeamsController_getTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamOutputResponseDto" } } } } }, "summary": "Get a team", "tags": ["Orgs / Teams"], "x-oauth-scopes": ["TEAM_PROFILE_READ"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `team.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_PROFILE_WRITE` scope is required.", "operationId": "OrganizationsTeamsController_deleteTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamOutputResponseDto" } } } } }, "summary": "Delete a team", "tags": ["Orgs / Teams"], "x-oauth-scopes": ["ORG_PROFILE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_PROFILE_WRITE` scope is required.", "operationId": "OrganizationsTeamsController_updateTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgTeamDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamOutputResponseDto" } } } } }, "summary": "Update a team", "tags": ["Orgs / Teams"], "x-oauth-scopes": ["ORG_PROFILE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/bookings": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `booking.readTeamBookings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_BOOKING_READ` scope is required.", "operationId": "OrganizationsTeamsBookingsController_getAllOrgTeamBookings", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter bookings by status. If you want to filter by multiple statuses, separate them with a comma.", "schema": { "minItems": 1, "example": "?status=upcoming,past", "type": "array", "items": { "type": "string", "enum": ["upcoming", "recurring", "past", "cancelled", "unconfirmed"] } } }, { "name": "attendeeEmail", "required": false, "in": "query", "description": "Filter bookings by the attendee's email address.", "schema": { "example": "example@domain.com", "type": "string" } }, { "name": "attendeeName", "required": false, "in": "query", "description": "Filter bookings by the attendee's name.", "schema": { "example": "John Doe", "type": "string" } }, { "name": "bookingUid", "required": false, "in": "query", "description": "Filter bookings by the booking Uid.", "schema": { "example": "2NtaeaVcKfpmSZ4CthFdfk", "type": "string" } }, { "name": "eventTypeIds", "required": false, "in": "query", "description": "Filter bookings by event type ids. Event type ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?eventTypeIds=100,200", "type": "string" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter bookings by event type id.", "schema": { "example": "?eventTypeId=100", "type": "string" } }, { "name": "afterStart", "required": false, "in": "query", "description": "Filter bookings with start after this date string.", "schema": { "example": "?afterStart=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeEnd", "required": false, "in": "query", "description": "Filter bookings with end before this date string.", "schema": { "example": "?beforeEnd=2025-03-07T11:00:00.000Z", "type": "string" } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created after this date string.", "schema": { "example": "?afterCreatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created before this date string.", "schema": { "example": "?beforeCreatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated after this date string.", "schema": { "example": "?afterUpdatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated before this date string.", "schema": { "example": "?beforeUpdatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortCreated", "required": false, "in": "query", "description": "Sort results by their creation time (when booking was made) in ascending or descending order.", "schema": { "example": "?sortCreated=asc OR ?sortCreated=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort results by their updated time (for example when booking status changes) in ascending or descending order.", "schema": { "example": "?sortUpdatedAt=asc OR ?sortUpdatedAt=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "take", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 100, "example": 10, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "The number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingsOutput_2024_08_13" } } } } }, "summary": "Get organization team bookings", "tags": ["Orgs / Teams / Bookings"], "x-mcp": { "name": "get_org_team_bookings", "guidance": "List all bookings for a team within an organization. Requires TEAM_ADMIN role. Supports filtering by status (upcoming, recurring, past, cancelled, unconfirmed), attendee email/name, event type, date ranges (afterStart, beforeEnd, afterCreatedAt, beforeCreatedAt, afterUpdatedAt, beforeUpdatedAt), and sorting (sortStart, sortEnd, sortCreated, sortUpdatedAt)." }, "x-oauth-scopes": ["TEAM_BOOKING_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/bookings/{bookingUid}/references": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `booking.readTeamBookings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_BOOKING_READ` scope is required.", "operationId": "OrganizationsTeamsBookingsController_getBookingReferences", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter booking references by type", "schema": { "example": "google_calendar", "type": "string", "enum": [ "google_calendar", "office365_calendar", "daily_video", "google_video", "office365_video", "zoom_video" ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReferencesOutput_2024_08_13" } } } } }, "summary": "Get booking references", "tags": ["Orgs / Teams / Bookings"], "x-oauth-scopes": ["TEAM_BOOKING_READ"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/connect": { "post": { "description": "Only `google-meet` can be connected this way, and only for a team that already has a valid Google Calendar connection. Zoom and Microsoft Teams require an OAuth handshake - start it with `GET /v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/oauth/auth-url` instead. Walkthrough: https://cal.com/docs/api-reference/v2/conferencing-apps. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_connectTeamApp", "parameters": [ { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["google-meet"], "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferencingAppOutputResponseDto" } } } } }, "summary": "Connect your conferencing application to a team", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/oauth/auth-url": { "get": { "description": "Returns the URL to send a team admin to so they can authorize Zoom or Microsoft Teams for the team. Redirect their browser to it - the provider then returns them to a callback already registered by Cal.com, which stores the credential against the team rather than against the admin who authorized it. To cover every team in the organization with a single handshake, use `GET /v2/organizations/{orgId}/conferencing/{app}/oauth/auth-url` instead. `returnTo` and `onErrorReturnTo` must each be a relative path or an absolute http(s) URL. The returned URL expires 10 minutes after this call, so redirect immediately rather than caching it. Walkthrough: https://cal.com/docs/api-reference/v2/conferencing-apps. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_getTeamOAuthUrl", "parameters": [ { "name": "Authorization", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["zoom", "msteams"], "type": "string" } }, { "name": "returnTo", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "onErrorReturnTo", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConferencingAppsOauthUrlResponseDto" } } } } }, "summary": "Get OAuth conferencing app's auth URL for a team", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readConferencing`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_READ` scope is required.", "operationId": "OrganizationsConferencingController_listTeamConferencingApps", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferencingAppsOutputResponseDto" } } } } }, "summary": "List team conferencing applications", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/default": { "post": { "description": "Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_setTeamDefaultApp", "parameters": [ { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["google-meet", "zoom", "msteams", "daily-video"], "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultConferencingAppOutputResponseDto" } } } } }, "summary": "Set team default conferencing application", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing/default": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readConferencing`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_READ` scope is required.", "operationId": "OrganizationsConferencingController_getTeamDefaultApp", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDefaultConferencingAppOutputResponseDto" } } } } }, "summary": "Get team default conferencing application", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/disconnect": { "delete": { "description": "Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_disconnectTeamApp", "parameters": [ { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["google-meet", "zoom", "msteams"], "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectConferencingAppOutputResponseDto" } } } } }, "summary": "Disconnect team conferencing application", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/oauth/callback": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_saveTeamOauthCredentials", "parameters": [ { "name": "state", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "app", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "" } }, "summary": "Save conferencing app OAuth credentials", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/conferencing/{app}/oauth/auth-url": { "get": { "description": "Returns the URL to send an organization admin to so they can authorize Zoom or Microsoft Teams once for the whole organization. The resulting credential is owned by the organization, so every team and member below it can use the app without its own OAuth handshake. Redirect their browser to it - the provider then returns them to a callback already registered by Cal.com. `returnTo` and `onErrorReturnTo` must each be a relative path or an absolute http(s) URL. The returned URL expires 10 minutes after this call, so redirect immediately rather than caching it. Walkthrough: https://cal.com/docs/api-reference/v2/conferencing-apps. Required membership role: `org admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_getOrgOAuthUrl", "parameters": [ { "name": "Authorization", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["zoom", "msteams"], "type": "string" } }, { "name": "returnTo", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "onErrorReturnTo", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConferencingAppsOauthUrlResponseDto" } } } } }, "summary": "Get OAuth conferencing app's auth URL for an organization", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/conferencing/{app}/oauth/callback": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_saveOrgOauthCredentials", "parameters": [ { "name": "state", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["zoom", "msteams"], "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Save organization conferencing app OAuth credentials", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/conferencing": { "get": { "description": "Lists the conferencing apps installed on the organization itself, not those installed on its teams or members. Required membership role: `org admin`. PBAC permission: `team.readConferencing`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_READ` scope is required.", "operationId": "OrganizationsConferencingController_listOrgConferencingApps", "parameters": [ { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferencingAppsOutputResponseDto" } } } } }, "summary": "List organization conferencing applications", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/conferencing/{app}/disconnect": { "delete": { "description": "Required membership role: `org admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_APPS_WRITE` scope is required.", "operationId": "OrganizationsConferencingController_disconnectOrgApp", "parameters": [ { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["zoom", "msteams"], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectConferencingAppOutputResponseDto" } } } } }, "summary": "Disconnect organization conferencing application", "tags": ["Orgs / Teams / Conferencing"], "x-oauth-scopes": ["TEAM_APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-type-sequences": { "post": { "description": "Lets a booker book the team's event types back to back, as one loop. Every segment's event type must belong to the team and be bookable together: a 422 names each segment that isn't and why, and a slug already used by one of the team's sequences or event types is a 409. PBAC permission: `eventType.create`. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsTeamsEventTypeSequencesController_create", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventTypeSequenceInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeSequenceResponseOutput" } } } } }, "summary": "Create an event type sequence", "tags": ["Orgs / Teams / Event Type Sequences"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "get": { "description": "Returns the team's sequences in creation order, each checked against its segments' event types as they are now. PBAC permission: `eventType.read` for a team member, or `eventType.readTeamEventTypes` for anyone else in the organization. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "OrganizationsTeamsEventTypeSequencesController_list", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "The `nextCursor` of the previous page.", "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 50, "default": 50, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeSequencesOutput" } } } } }, "summary": "List event type sequences", "tags": ["Orgs / Teams / Event Type Sequences"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] } }, "/v2/organizations/{orgId}/teams/{teamId}/event-type-sequences/{uid}": { "get": { "description": "Includes whether the sequence can be booked right now and, for each segment that can't, why. PBAC permission: `eventType.read` for a team member, or `eventType.readTeamEventTypes` for anyone else in the organization. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "OrganizationsTeamsEventTypeSequencesController_get", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "uid", "required": true, "in": "path", "description": "The sequence's `uid`.", "schema": { "format": "uuid", "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeSequenceResponseOutput" } } } } }, "summary": "Get an event type sequence", "tags": ["Orgs / Teams / Event Type Sequences"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "patch": { "description": "Changes only the fields sent; `segments` replaces every segment and is checked like a new sequence. PBAC permission: `eventType.update`. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsTeamsEventTypeSequencesController_update", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "uid", "required": true, "in": "path", "description": "The sequence's `uid`.", "schema": { "format": "uuid", "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventTypeSequenceInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeSequenceResponseOutput" } } } } }, "summary": "Update an event type sequence", "tags": ["Orgs / Teams / Event Type Sequences"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "delete": { "description": "Loops already booked stay: each of their segments is a normal booking of its event type. PBAC permission: `eventType.delete`. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsTeamsEventTypeSequencesController_delete", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "uid", "required": true, "in": "path", "description": "The sequence's `uid`.", "schema": { "format": "uuid", "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "204": { "description": "" } }, "summary": "Delete an event type sequence", "tags": ["Orgs / Teams / Event Type Sequences"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/private-links": { "post": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesPrivateLinksController_2024_09_04_createPrivateLink", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrivateLinkInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrivateLinkOutput" } } } } }, "summary": "Create a private link for a team event type", "tags": ["Orgs / Teams / Event Types / Private Links"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "get": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "OrganizationsEventTypesPrivateLinksController_2024_09_04_getPrivateLinks", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPrivateLinksOutput" } } } } }, "summary": "Get all private links for a team event type", "tags": ["Orgs / Teams / Event Types / Private Links"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/private-links/{linkId}": { "patch": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesPrivateLinksController_2024_09_04_updatePrivateLink", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "linkId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePrivateLinkOutput" } } } } }, "summary": "Update a private link for a team event type", "tags": ["Orgs / Teams / Event Types / Private Links"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesPrivateLinksController_2024_09_04_deletePrivateLink", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "linkId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePrivateLinkOutput" } } } } }, "summary": "Delete a private link for a team event type", "tags": ["Orgs / Teams / Event Types / Private Links"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/invite": { "post": { "description": "Required membership role: `team admin`. PBAC permission: `team.invite`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsTeamsInviteController_createInvite", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteOutputDto" } } } } }, "summary": "Create team invite link", "tags": ["Orgs / Teams / Invite"], "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"] } }, "/v2/organizations/{orgId}/teams/{teamId}/memberships": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_READ` scope is required.", "operationId": "OrganizationsTeamsMembershipsController_getAllOrgTeamMemberships", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamMembershipsOutputResponseDto" } } } } }, "summary": "Get all memberships", "tags": ["Orgs / Teams / Memberships"], "x-oauth-scopes": ["TEAM_MEMBERSHIP_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `team admin`. PBAC permission: `team.invite`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsTeamsMembershipsController_createOrgTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgTeamMembershipDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamMembershipOutputResponseDto" } } } } }, "summary": "Create a membership", "tags": ["Orgs / Teams / Memberships"], "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/memberships/{membershipId}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_READ` scope is required.", "operationId": "OrganizationsTeamsMembershipsController_getOrgTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamMembershipOutputResponseDto" } } } } }, "summary": "Get a membership", "tags": ["Orgs / Teams / Memberships"], "x-oauth-scopes": ["TEAM_MEMBERSHIP_READ"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `team admin`. PBAC permission: `team.remove`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsTeamsMembershipsController_deleteOrgTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamMembershipOutputResponseDto" } } } } }, "summary": "Delete a membership", "tags": ["Orgs / Teams / Memberships"], "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `team admin`. PBAC permission: `team.changeMemberRole`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsTeamsMembershipsController_updateOrgTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgTeamMembershipDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamMembershipOutputResponseDto" } } } } }, "summary": "Update a membership", "tags": ["Orgs / Teams / Memberships"], "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/roles": { "post": { "operationId": "OrganizationsTeamsRolesController_createRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRoleInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRoleOutput" } } } } }, "summary": "Create a new organization team role", "tags": ["Orgs / Teams / Roles"], "x-platform-plan": "SCALE" }, "get": { "description": "Required membership role: `org admin`. PBAC permission: `role.readTeamRoles`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsTeamsRolesController_getAllRoles", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllTeamRolesOutput" } } } } }, "summary": "Get all organization team roles", "tags": ["Orgs / Teams / Roles"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/roles/{roleId}": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `role.readTeamRoles`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsTeamsRolesController_getRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRoleOutput" } } } } }, "summary": "Get a specific organization team role", "tags": ["Orgs / Teams / Roles"], "x-platform-plan": "SCALE" }, "patch": { "operationId": "OrganizationsTeamsRolesController_updateRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRoleInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRoleOutput" } } } } }, "summary": "Update an organization team role", "tags": ["Orgs / Teams / Roles"], "x-platform-plan": "SCALE" }, "delete": { "operationId": "OrganizationsTeamsRolesController_deleteRole", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTeamRoleOutput" } } } } }, "summary": "Delete an organization team role", "tags": ["Orgs / Teams / Roles"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/roles/{roleId}/permissions": { "post": { "operationId": "OrganizationsTeamsRolesPermissionsController_addPermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRolePermissionsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRolePermissionsOutput" } } } } }, "summary": "Add permissions to an organization team role (single or batch)", "tags": ["Orgs / Teams / Roles / Permissions"], "x-platform-plan": "SCALE" }, "get": { "description": "Required membership role: `org admin`. PBAC permission: `role.readTeamRoles`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsTeamsRolesPermissionsController_listPermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRolePermissionsOutput" } } } } }, "summary": "List permissions for an organization team role", "tags": ["Orgs / Teams / Roles / Permissions"], "x-platform-plan": "SCALE" }, "put": { "operationId": "OrganizationsTeamsRolesPermissionsController_setPermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRolePermissionsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRolePermissionsOutput" } } } } }, "summary": "Replace all permissions for an organization team role", "tags": ["Orgs / Teams / Roles / Permissions"], "x-platform-plan": "SCALE" }, "delete": { "operationId": "OrganizationsTeamsRolesPermissionsController_removePermissions", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "permissions", "required": false, "in": "query", "description": "Permissions to remove (format: resource.action). Supports comma-separated values as well as repeated query params.", "schema": { "example": "?permissions=eventType.read,booking.read", "type": "array", "items": { "type": "string", "enum": [ "role.create", "role.read", "role.readTeamRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.read", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "booking.read", "booking.readTeamBookings", "booking.readRecordings", "booking.update", "booking.updateTeamBookings", "booking.reassignTeamPastBookings", "booking.readTeamAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readTeamAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.updateTeamAvailability", "featureOptIn.read", "featureOptIn.update", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] } } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "204": { "description": "" } }, "summary": "Remove multiple permissions from an organization team role", "tags": ["Orgs / Teams / Roles / Permissions"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/roles/{roleId}/permissions/{permission}": { "delete": { "operationId": "OrganizationsTeamsRolesPermissionsController_removePermission", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "permission", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "summary": "Remove a permission from an organization team role", "tags": ["Orgs / Teams / Roles / Permissions"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.readTeamRoutingForms`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_READ` scope is required.", "operationId": "OrganizationsTeamsRoutingFormsController_getTeamRoutingForms", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of responses to skip", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of responses to take", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort by creation time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort by update time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter by responses created before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter by responses updated before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "routedToBookingUid", "required": false, "in": "query", "description": "Filter by responses routed to a specific booking", "schema": { "type": "string" } }, { "name": "disabled", "required": false, "in": "query", "description": "Filter by disabled status", "schema": { "type": "boolean" } }, { "name": "name", "required": false, "in": "query", "description": "Filter by name", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormsOutput" } } } } }, "summary": "Get team routing forms", "tags": ["Orgs / Teams / Routing forms"], "x-mcp": { "name": "get_team_routing_forms", "guidance": "List routing forms that belong to a team in an organization. Use this as a team admin; get_org_routing_forms requires an organization admin. Use get_my_teams or get_org_teams to find teamId. Supports filtering by name (case-insensitive substring) and disabled status, created/updated date range filters, sorting by created/updated date, and skip/take pagination. Use get_routing_form with a returned id to read its questions and routes.", "hints": { "readOnly": true } }, "x-oauth-scopes": ["TEAM_ROUTING_FORM_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_WRITE` scope is required. The form is created with no questions and a fallback route.", "operationId": "OrganizationsTeamsRoutingFormsController_createTeamRoutingForm", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRoutingFormInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRoutingFormOutput" } } } } }, "summary": "Create team routing form", "tags": ["Orgs / Teams / Routing forms"], "x-mcp": { "name": "create_routing_form", "guidance": "Create a routing form for a team in an organization, from a name and an optional description. Confirm the name and the team with the user before calling; use get_my_teams or get_org_teams to find teamId and never guess it. Each call creates a new form, so never call it again to retry or to rename a form. The form starts with no questions and one fallback route, and is returned with its id, routes and updatedAt. To change its routes, pass the returned routes and updatedAt straight to edit_routing_form_routes, and don't call get_routing_form right after creating the form, because it can briefly miss a new form. This tool does not add questions, and until the form has questions the only route change that applies is setFallback." }, "x-oauth-scopes": ["TEAM_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms/{routingFormId}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.readTeamRoutingForms`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_READ` scope is required.", "operationId": "OrganizationsTeamsRoutingFormsController_getTeamRoutingForm", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRoutingFormOutput" } } } } }, "summary": "Get team routing form", "tags": ["Orgs / Teams / Routing forms"], "x-mcp": { "name": "get_routing_form", "guidance": "Get one team routing form: its questions (id, label, identifier, type, required, hidden, options) and its routes in evaluation order (id, name, kind, action, readable conditions). Call this before changing a form's routes or questions: route edits reference the route ids and question labels returned here, question edits reference the question and option ids, and applying an edit requires the form's updatedAt. Use get_team_routing_forms to find routingFormId; never guess route, question or option ids.", "hints": { "readOnly": true } }, "x-oauth-scopes": ["TEAM_ROUTING_FORM_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms/{routingFormId}/history": { "get": { "description": "Required membership role: `org member`. PBAC permission: `routingForm.readTeamAuditLogs` on the team or `routingForm.readOrgAuditLogs` on the organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_READ` scope is required. Returns the form's change history, newest first.", "operationId": "OrganizationsTeamsRoutingFormsController_getTeamRoutingFormHistory", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of history entries to return.", "schema": { "minimum": 1, "maximum": 50, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Pass `pagination.nextCursor` from the previous response to fetch older entries.", "schema": { "format": "uuid", "example": "019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b", "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamRoutingFormHistoryOutput" } } } } }, "summary": "Get team routing form history", "tags": ["Orgs / Teams / Routing forms"], "x-mcp": { "name": "get_routing_form_history", "guidance": "Get the change history of a team routing form, newest first: each entry has an id, a timestamp, who made the change, and what changed (questions, routes, route conditions and settings, with before and after values). Use it to see what changed on a form and when, and to review its recent changes before and after editing it with edit_routing_form_routes; a new edit can take a few seconds to appear. Use get_team_routing_forms to find routingFormId. Supports cursor pagination: limit (1-50, default 25) and cursor set to pagination.nextCursor.", "hints": { "readOnly": true } }, "x-oauth-scopes": ["TEAM_ROUTING_FORM_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms/{routingFormId}/routes": { "patch": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_WRITE` scope is required. Previews by default (`dryRun` defaults to true); send `dryRun: false` with `expectedUpdatedAt` to save.", "operationId": "OrganizationsTeamsRoutingFormsController_editTeamRoutingFormRoutes", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditTeamRoutingFormRoutesInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditTeamRoutingFormRoutesOutput" } } } } }, "summary": "Edit team routing form routes", "tags": ["Orgs / Teams / Routing forms"], "x-mcp": { "name": "edit_routing_form_routes", "guidance": "Edit the routes of an existing team routing form: add, replace, remove or move routes, or change the fallback. Call get_routing_form first, refer to routes by the routeId it returns and to questions by their exact label, and never guess ids. Send only the operations that change something, never the full routes array: untouched routes keep their ids and settings. Always preview first with dryRun: true (the default), show the user the returned changes and warnings, and get their confirmation. Then send the same operations with dryRun: false and expectedUpdatedAt set to the updatedAt from the preview. A 409 means the form changed after the preview: call get_routing_form again, rebuild and preview the edit, and ask for confirmation again; never retry an apply blindly. Routes are evaluated top to bottom and the first match wins, so put the most specific routes first (position is 0-based among non-fallback routes; add appends when omitted). Multiselect questions have no equals: all_in means every selected option is in the list, so it is a subset test. An unanswered optional question counts as empty, and an empty value matches not_equals, not_contains, not_all_in, less_than, less_or_equal and ends_with; make the question required, or route on a choice question with explicit options, when that would catch the wrong people. Number questions support only equals, not_equals, greater_than, less_than, greater_or_equal, less_or_equal and between; use non-overlapping ranges. Router routes can be moved or removed but not replaced. Change the fallback only with setFallback. On a route to a round-robin event type, memberFilter limits the hosts to team members whose attributes match, and fallbackMemberFilter (same shape) sets the hosts used when memberFilter matches nobody. Fallback rules need attribute rules on the route: send memberFilter too, or replace a route that already has them. A route whose own fallback action (set in the route builder, not the form fallback that setFallback changes) shows a message or redirects to a URL never uses fallback rules, so the edit is refused. On replace, omitting memberFilter or fallbackMemberFilter keeps the stored rules; get_routing_form only counts them in its summary, so omit them rather than rebuilding rules you cannot read. Attach examples (answers keyed by question label, and the expectedRoute they must reach: a route id, route name or event-type slug, or null for the fallback) so the server checks that the edited routes catch the intended answers; a failed example rejects the edit with 400.", "hints": { "destructive": true } }, "x-oauth-scopes": ["TEAM_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms/{routingFormId}/fields": { "patch": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_WRITE` scope is required. Previews by default (`dryRun` defaults to true); send `dryRun: false` with `expectedUpdatedAt` to save.", "operationId": "OrganizationsTeamsRoutingFormsController_editTeamRoutingFormFields", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditTeamRoutingFormFieldsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditTeamRoutingFormFieldsOutput" } } } } }, "summary": "Edit team routing form fields", "tags": ["Orgs / Teams / Routing forms"], "x-mcp": { "name": "edit_routing_form_fields", "guidance": "Edit the questions of an existing team routing form: add, update or remove questions. Call get_routing_form first and refer to existing questions by the fieldId it returns and to their options by option id; a label only names a new question, and ids are never guessed. Send only the operations that change something: every route and every untouched question keeps its id and settings, and an update changes only the properties it lists. To change a choice question's options, send its complete option list in display order: keep each existing option's id (a renamed option keeps its id, so routes comparing against it keep matching), omit the id for a new option, and leave an option out to remove it. A question's type can't be changed; remove it and add a new one. Position is 0-based among the form's questions, and add appends when it is omitted. Always preview first with dryRun: true (the default), show the user the returned changes and warnings, and get their confirmation. Then send the same operations with dryRun: false and expectedUpdatedAt set to the updatedAt from the preview. A 409 means the form changed after the preview: call get_routing_form again, rebuild and preview the edit, and ask for confirmation again; never retry an apply blindly. Removing a question or an option that a route uses (on this form or on a form that routes through it) is rejected with 400: change or remove that route first with edit_routing_form_routes. A hidden question is not shown to the booker and takes its answer from a URL parameter named after its identifier, e.g. a hidden \"Lead Source\" filled in by the link the lead clicked; a hidden question can't be required. Renaming a question without an explicit identifier changes the key prefilled links use; the preview warns when that happens.", "hints": { "destructive": true } }, "x-oauth-scopes": ["TEAM_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms/{routingFormId}/responses": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.readResponsePii`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_READ` scope is required.", "operationId": "OrganizationsTeamsRoutingFormsResponsesController_getRoutingFormResponses", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of responses to skip", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of responses to take", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort by creation time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort by update time", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter by responses created before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter by responses created after this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter by responses updated before this date", "schema": { "format": "date-time", "type": "string" } }, { "name": "routedToBookingUid", "required": false, "in": "query", "description": "Filter by responses routed to a specific booking", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormResponsesOutput" } } } } }, "summary": "Get organization team routing form responses", "tags": ["Orgs / Teams / Routing forms / Responses"], "x-oauth-scopes": ["TEAM_ROUTING_FORM_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `team member`. PBAC permission: `routingForm.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_WRITE` scope is required.", "operationId": "OrganizationsTeamsRoutingFormsResponsesController_createRoutingFormResponse", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "start", "required": true, "in": "query", "description": "\n Time starting from which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to start of day or specify hours:\n 2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z\n ", "schema": { "example": "2033-09-05", "type": "string" } }, { "name": "end", "required": true, "in": "query", "description": "\n Time until which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to end of day or specify hours:\n 2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z", "schema": { "example": "2033-09-06", "type": "string" } }, { "name": "timeZone", "required": false, "in": "query", "description": "Time zone in which the available slots should be returned. Defaults to UTC.", "schema": { "example": "Europe/Rome", "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "If event type has multiple possible durations then you can specify the desired duration here. Also, if you are fetching slots for a dynamic event then you can specify the duration her which defaults to 30, meaning that returned slots will be each 30 minutes long.", "schema": { "example": "60", "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Format of slot times in response. Use 'range' to get start and end times.", "schema": { "example": "range", "type": "string", "enum": ["range", "time"] } }, { "name": "bookingUidToReschedule", "required": false, "in": "query", "description": "The unique identifier of the booking being rescheduled. When provided will ensure that the original booking time appears within the returned available slots when rescheduling.", "schema": { "example": "abc123def456", "type": "string" } }, { "name": "rescheduleWithSameHost", "required": false, "in": "query", "description": "Only for round robin event types that allow the person rescheduling to choose the host. True returns slots of the original host, false returns slots of any available host. Ignored for other event types.", "schema": { "example": true, "type": "boolean" } }, { "name": "queueResponse", "required": false, "in": "query", "description": "Whether to queue the form response.", "schema": { "example": true, "type": "boolean" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingFormResponseOutput" } } } } }, "summary": "Create routing form response and get available slots", "tags": ["Orgs / Teams / Routing forms / Responses"], "x-oauth-scopes": ["TEAM_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/routing-forms/{routingFormId}/responses/{responseId}": { "patch": { "description": "Required membership role: `team admin`. PBAC permission: `routingForm.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_WRITE` scope is required.", "operationId": "OrganizationsTeamsRoutingFormsResponsesController_updateRoutingFormResponse", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "responseId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingFormResponseInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingFormResponseOutput" } } } } }, "summary": "Update routing form response", "tags": ["Orgs / Teams / Routing forms / Responses"], "x-oauth-scopes": ["TEAM_ROUTING_FORM_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/schedules": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `availability.readTeamAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsTeamsSchedulesController_getTeamSchedules", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter schedules by event type ID", "schema": { "example": 1, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulesOutput_2024_06_11" } } } } }, "summary": "Get all team member schedules", "tags": ["Orgs / Teams / Schedules"], "x-oauth-scopes": ["TEAM_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/stripe/connect": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `organization.manageBilling`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsStripeController_getTeamStripeConnectUrl", "parameters": [ { "name": "Authorization", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "returnTo", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "onErrorReturnTo", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripConnectOutputResponseDto" } } } } }, "summary": "Get Stripe connect URL for a team", "tags": ["Orgs / Teams / Stripe"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/stripe/check": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `organization.manageBilling`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsStripeController_checkTeamStripeConnection", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripCredentialsCheckOutputResponseDto" } } } } }, "summary": "Check team Stripe connection", "tags": ["Orgs / Teams / Stripe"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/stripe/save": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `organization.manageBilling`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsStripeController_save", "parameters": [ { "name": "state", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripCredentialsSaveOutputResponseDto" } } } } }, "summary": "Save Stripe credentials", "tags": ["Orgs / Teams / Stripe"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/users/{userId}/schedules": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `availability.readTeamAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsTeamsSchedulesController_getUserSchedules", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter schedules by event type ID", "schema": { "example": 1, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulesOutput_2024_06_11" } } } } }, "summary": "Get schedules of a team member", "tags": ["Orgs / Teams / Users / Schedules"], "x-oauth-scopes": ["TEAM_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/workflows/routing-form": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.readTeamWorkflows`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_READ` scope is required.", "operationId": "OrganizationTeamWorkflowsController_getRoutingFormWorkflows", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormWorkflowsOutput" } } } } }, "summary": "Get organization team routing form workflows", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_READ"], "x-platform-plan": "SCALE" }, "post": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_WRITE` scope is required.", "operationId": "OrganizationTeamWorkflowsController_createFormWorkflow", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFormWorkflowDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormWorkflowOutput" } } } } }, "summary": "Create organization team workflow for routing-forms", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_WRITE"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/workflows/{workflowId}/routing-form": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.readTeamWorkflows`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_READ` scope is required.", "operationId": "OrganizationTeamWorkflowsController_getRoutingFormWorkflowById", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormWorkflowOutput" } } } } }, "summary": "Get organization team routing form workflow", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_READ"], "x-platform-plan": "SCALE" }, "patch": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_WRITE` scope is required.", "operationId": "OrganizationTeamWorkflowsController_updateRoutingFormWorkflow", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFormWorkflowDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoutingFormWorkflowOutput" } } } } }, "summary": "Update organization routing form team workflow", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_WRITE"], "x-platform-plan": "SCALE" }, "delete": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_WRITE` scope is required.", "operationId": "OrganizationTeamWorkflowsController_deleteRoutingFormWorkflow", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "summary": "Delete organization team routing-form workflow", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_WRITE"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/workflows": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.readTeamWorkflows`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_READ` scope is required.", "operationId": "OrganizationTeamWorkflowsController_getWorkflows", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowsOutput_2026_09_22" } } } } }, "summary": "Get organization team workflows", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_READ"], "x-platform-plan": "SCALE" }, "post": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_WRITE` scope is required.", "operationId": "OrganizationTeamWorkflowsController_createEventTypeWorkflow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventTypeWorkflowDto_2026_09_22" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowOutput_2026_09_22" } } } } }, "summary": "Create organization team workflow for event-types", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_WRITE"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/workflows/{workflowId}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.readTeamWorkflows`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_READ` scope is required.", "operationId": "OrganizationTeamWorkflowsController_getWorkflowById", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowOutput_2026_09_22" } } } } }, "summary": "Get organization team workflow", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_READ"], "x-platform-plan": "SCALE" }, "patch": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_WRITE` scope is required.", "operationId": "OrganizationTeamWorkflowsController_updateWorkflow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventTypeWorkflowDto_2026_09_22" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowOutput_2026_09_22" } } } } }, "summary": "Update organization team workflow", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_WRITE"], "x-platform-plan": "SCALE" }, "delete": { "description": "Required membership role: `team admin`. PBAC permission: `workflow.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_WORKFLOW_WRITE` scope is required.", "operationId": "OrganizationTeamWorkflowsController_deleteWorkflow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "summary": "Delete organization team workflow", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_WRITE"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/teams/{teamId}/workflows/{workflowId}/condition-fields": { "get": { "operationId": "OrganizationTeamWorkflowsController_2026_09_22_getConditionFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowConditionFieldsOutput" } } } } }, "summary": "Get organization team workflow condition fields", "tags": ["Orgs / Teams / Workflows"], "x-oauth-scopes": ["TEAM_WORKFLOW_READ"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/users": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `organization.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_READ` scope is required.", "operationId": "OrganizationsUsersController_getOrganizationsUsers", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 1000, "example": 10, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "The number of items to skip", "schema": { "minimum": 0, "example": 0, "type": "number" } }, { "name": "emails", "required": false, "in": "query", "description": "The email address or an array of email addresses to filter by", "schema": { "example": ["user1@example.com", "user2@example.com"], "type": "array", "items": { "type": "string" } } }, { "name": "assignedOptionIds", "required": false, "in": "query", "description": "Filter by assigned attribute option ids. ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?assignedOptionIds=aaaaaaaa-bbbb-cccc-dddd-eeeeee1eee,aaaaaaaa-bbbb-cccc-dddd-eeeeee2eee", "type": "array", "items": { "type": "string" } } }, { "name": "attributeQueryOperator", "required": false, "in": "query", "description": "Query operator used to filter assigned options, AND by default.", "schema": { "default": "AND", "example": "NONE", "type": "string", "enum": ["OR", "AND", "NONE"] } }, { "name": "teamIds", "required": false, "in": "query", "description": "Filter by teamIds. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=100,200", "type": "array", "items": { "type": "number" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganizationUsersResponseDTO" } } } } }, "summary": "Get all users", "tags": ["Orgs / Users"], "x-oauth-scopes": ["ORG_MEMBERSHIP_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `organization.invite`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_WRITE` scope is required.\n\nThis endpoint creates a brand-new Cal.com user account and attaches them to the organization. If the email already belongs to an existing Cal.com user, the request fails with `409 Conflict`. When the user is already a member of this organization the message is `A user already exists with that email and is already a member of this organization`. When the user exists but is not a member, the message is `A user already exists with this email. Use POST /v2/organizations/{orgId}/memberships to add them to this organization.`. A common case is re-adding someone who was previously removed from the organization via the dashboard: the membership is gone, but the underlying Cal.com user account still exists.\n\nTo attach an existing Cal.com user to the organization, use `POST /v2/organizations/{orgId}/memberships` with the `email` field instead.\n\nMembership is accepted automatically only when `autoAccept` is `true`, the organization is verified, and the email's domain is its auto-accept domain or one of its verified secondary domains. An email outside those domains creates a pending membership with no organization profile and always sends an invite email, even when `skipNotificationEmail` is `true`. Until the user accepts the invite, these outside-domain users are not returned by `GET /v2/organizations/{orgId}/users`, and `/v2/organizations/{orgId}/users/{userId}/...` routes return `403`.\n\nA matching-domain user keeps an organization profile even when their membership is pending because `autoAccept` is `false` or the organization is unverified. These users remain listed and accessible through organization-user routes. An unverified organization still triggers an invite, even when `skipNotificationEmail` is `true`.\n\nPlatform organizations follow the same rule. With no organization settings, or an auto-accept domain of `UNUSED_FOR_PLATFORM` and no matching verified secondary domain, users get a pending membership, no organization profile, and a Cal.com invite even when `skipNotificationEmail` is `true`. Platform-managed user creation through `POST /v2/oauth-clients/{clientId}/users` is a separate flow and is unchanged.\n\nThe response includes `membership.id` and `membership.accepted`. When `accepted` is `false`, the membership is pending until the user accepts the invite; poll `GET /v2/organizations/{orgId}/memberships/{membershipId}` with `membership.id` until `accepted` is `true`.", "operationId": "OrganizationsUsersController_createOrganizationUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationUserInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationUserOutput" } } } } }, "summary": "Create a user", "tags": ["Orgs / Users"], "x-oauth-scopes": ["ORG_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}": { "patch": { "description": "Required membership role: `org admin`. PBAC permission: `organization.editUsers`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsUsersController_updateOrganizationUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationUserInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganizationUserOutput" } } } } }, "summary": "Update a user", "tags": ["Orgs / Users"], "x-oauth-scopes": ["ORG_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `organization.remove`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_MEMBERSHIP_WRITE` scope is required.", "operationId": "OrganizationsUsersController_deleteOrganizationUser", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganizationUserOutput" } } } } }, "summary": "Delete a user", "tags": ["Orgs / Users"], "x-oauth-scopes": ["ORG_MEMBERSHIP_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/bookings": { "get": { "description": "If accessed using an OAuth access token, the `ORG_BOOKING_READ` scope is required.", "operationId": "OrganizationsUsersBookingsController_getOrganizationUserBookings", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "Filter bookings by status. If you want to filter by multiple statuses, separate them with a comma.", "schema": { "minItems": 1, "example": "?status=upcoming,past", "type": "array", "items": { "type": "string", "enum": ["upcoming", "recurring", "past", "cancelled", "unconfirmed"] } } }, { "name": "attendeeEmail", "required": false, "in": "query", "description": "Filter bookings by the attendee's email address.", "schema": { "example": "example@domain.com", "type": "string" } }, { "name": "attendeeName", "required": false, "in": "query", "description": "Filter bookings by the attendee's name.", "schema": { "example": "John Doe", "type": "string" } }, { "name": "bookingUid", "required": false, "in": "query", "description": "Filter bookings by the booking Uid.", "schema": { "example": "2NtaeaVcKfpmSZ4CthFdfk", "type": "string" } }, { "name": "eventTypeIds", "required": false, "in": "query", "description": "Filter bookings by event type ids. Event type ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?eventTypeIds=100,200", "type": "string" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter bookings by event type id.", "schema": { "example": "?eventTypeId=100", "type": "string" } }, { "name": "teamsIds", "required": false, "in": "query", "description": "Filter bookings by team ids that user is part of. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=50,60", "type": "string" } }, { "name": "teamId", "required": false, "in": "query", "description": "Filter bookings by team id that user is part of", "schema": { "example": "?teamId=50", "type": "string" } }, { "name": "afterStart", "required": false, "in": "query", "description": "Filter bookings with start after this date string.", "schema": { "example": "?afterStart=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeEnd", "required": false, "in": "query", "description": "Filter bookings with end before this date string.", "schema": { "example": "?beforeEnd=2025-03-07T11:00:00.000Z", "type": "string" } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created after this date string.", "schema": { "example": "?afterCreatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created before this date string.", "schema": { "example": "?beforeCreatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated after this date string.", "schema": { "example": "?afterUpdatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated before this date string.", "schema": { "example": "?beforeUpdatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortCreated", "required": false, "in": "query", "description": "Sort results by their creation time (when booking was made) in ascending or descending order.", "schema": { "example": "?sortCreated=asc OR ?sortCreated=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort results by their updated time (for example when booking status changes) in ascending or descending order.", "schema": { "example": "?sortUpdatedAt=asc OR ?sortUpdatedAt=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "take", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 100, "example": 10, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "The number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "" } }, "summary": "Get all bookings for an organization user", "tags": ["Orgs / Users / Bookings"], "x-mcp": { "name": "get_org_user_bookings", "guidance": "List all bookings for a specific user within an organization. Requires ORG_ADMIN role. Use get_org_memberships to find user IDs. Supports filtering by status, attendee email/name, event type, team, date ranges, and sorting." }, "x-oauth-scopes": ["ORG_BOOKING_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/conferencing": { "get": { "description": "Lists all connected conferencing apps for a specific user within the organization, including which one is set as default. Required membership role: `org admin`. PBAC permission: `team.readConferencing`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "OrganizationsUsersConferencingController_listConferencingApps", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferencingAppsWithDefaultOutputResponseDto" } } } } }, "summary": "List conferencing apps of an organization user", "tags": ["Orgs / Users / Conferencing"], "x-oauth-scopes": ["APPS_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/conferencing/default": { "post": { "description": "Sets the default conferencing app for a specific user within the organization. Required membership role: `org admin`. PBAC permission: `organization.editUsers`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "OrganizationsUsersConferencingController_setDefaultConferencingApp", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultConferencingAppInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultConferencingAppOutputResponseDto" } } } } }, "summary": "Set the default conferencing app for an organization user", "tags": ["Orgs / Users / Conferencing"], "x-oauth-scopes": ["APPS_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/ooo": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `ooo.readOrgOoo`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsUsersOOOController_getOrganizationUserOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOoosOutputResponseDto" } } } } }, "summary": "Get all out-of-office entries for a user", "tags": ["Orgs / Users / OOO"], "x-oauth-scopes": ["ORG_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "If accessed using an OAuth access token, the `ORG_SCHEDULE_WRITE` scope is required.", "operationId": "OrganizationsUsersOOOController_createOrganizationUserOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutOfOfficeEntryDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Create an out-of-office entry for a user", "tags": ["Orgs / Users / OOO"], "x-oauth-scopes": ["ORG_SCHEDULE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/ooo/{oooId}": { "patch": { "description": "If accessed using an OAuth access token, the `ORG_SCHEDULE_WRITE` scope is required.", "operationId": "OrganizationsUsersOOOController_updateOrganizationUserOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "oooId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOutOfOfficeEntryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Update an out-of-office entry for a user", "tags": ["Orgs / Users / OOO"], "x-oauth-scopes": ["ORG_SCHEDULE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "If accessed using an OAuth access token, the `ORG_SCHEDULE_WRITE` scope is required.", "operationId": "OrganizationsUsersOOOController_deleteOrganizationUserOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "oooId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Delete an out-of-office entry for a user", "tags": ["Orgs / Users / OOO"], "x-oauth-scopes": ["ORG_SCHEDULE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/ooo": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `ooo.readOrgOoo`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsUsersOOOController_getOrganizationUsersOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "email", "required": false, "in": "query", "description": "Filter ooo entries by the user email address. user must be within your organization.", "schema": { "example": "example@domain.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOoosOutputResponseDto" } } } } }, "summary": "Get all out-of-office entries for organization users", "tags": ["Orgs / Users / OOO"], "x-oauth-scopes": ["ORG_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/schedules": { "post": { "description": "Required membership role: `org admin`. PBAC permission: `availability.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_WRITE` scope is required.", "operationId": "OrganizationsSchedulesController_createUserSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleInput_2024_06_11" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleOutput_2024_06_11" } } } } }, "summary": "Create a schedule", "tags": ["Orgs / Users / Schedules"], "x-oauth-scopes": ["ORG_SCHEDULE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "get": { "description": "Required membership role: `org admin`. PBAC permission: `availability.readOrgAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsSchedulesController_getUserSchedules", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulesOutput_2024_06_11" } } } } }, "summary": "Get all schedules", "tags": ["Orgs / Users / Schedules"], "x-oauth-scopes": ["ORG_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/users/{userId}/schedules/{scheduleId}": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `availability.readOrgAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_READ` scope is required.", "operationId": "OrganizationsSchedulesController_getUserSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "scheduleId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetScheduleOutput_2024_06_11" } } } } }, "summary": "Get a schedule", "tags": ["Orgs / Users / Schedules"], "x-oauth-scopes": ["ORG_SCHEDULE_READ"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `availability.updateOrgAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_WRITE` scope is required.", "operationId": "OrganizationsSchedulesController_updateUserSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "scheduleId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleInput_2024_06_11" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleOutput_2024_06_11" } } } } }, "summary": "Update a schedule", "tags": ["Orgs / Users / Schedules"], "x-oauth-scopes": ["ORG_SCHEDULE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `availability.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_SCHEDULE_WRITE` scope is required.", "operationId": "OrganizationsSchedulesController_deleteUserSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "scheduleId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduleOutput_2024_06_11" } } } } }, "summary": "Delete a schedule", "tags": ["Orgs / Users / Schedules"], "x-oauth-scopes": ["ORG_SCHEDULE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/webhooks": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `webhook.readOrgWebhooks`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_WEBHOOK_READ` scope is required.", "operationId": "OrganizationsWebhooksController_getAllOrganizationWebhooks", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWebhooksOutputResponseDto" } } } } }, "summary": "Get all webhooks", "tags": ["Orgs / Webhooks"], "x-oauth-scopes": ["ORG_WEBHOOK_READ"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Required membership role: `org admin`. PBAC permission: `webhook.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_WEBHOOK_WRITE` scope is required.", "operationId": "OrganizationsWebhooksController_createOrganizationWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWebhookOutputResponseDto" } } } } }, "summary": "Create a webhook", "tags": ["Orgs / Webhooks"], "x-oauth-scopes": ["ORG_WEBHOOK_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/webhooks/{webhookId}": { "get": { "description": "Required membership role: `org admin`. PBAC permission: `webhook.readOrgWebhooks`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_WEBHOOK_READ` scope is required.", "operationId": "OrganizationsWebhooksController_getOrganizationWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWebhookOutputResponseDto" } } } } }, "summary": "Get a webhook", "tags": ["Orgs / Webhooks"], "x-oauth-scopes": ["ORG_WEBHOOK_READ"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Required membership role: `org admin`. PBAC permission: `webhook.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_WEBHOOK_WRITE` scope is required.", "operationId": "OrganizationsWebhooksController_deleteWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWebhookOutputResponseDto" } } } } }, "summary": "Delete a webhook", "tags": ["Orgs / Webhooks"], "x-oauth-scopes": ["ORG_WEBHOOK_WRITE"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Required membership role: `org admin`. PBAC permission: `webhook.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_WEBHOOK_WRITE` scope is required.", "operationId": "OrganizationsWebhooksController_updateOrgWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInputDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWebhookOutputResponseDto" } } } } }, "summary": "Update a webhook", "tags": ["Orgs / Webhooks"], "x-oauth-scopes": ["ORG_WEBHOOK_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/allowlists": { "get": { "description": "Returns the IPv4 ranges Cal.com sends traffic from and receives traffic on, keyed by service. Poll this endpoint instead of hard-coding addresses, because they can change.", "operationId": "AllowlistsController_getAllowlists", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllowlistsOutput" } } } } }, "summary": "Get the Cal.com IP allowlists", "tags": ["Allowlists"], "x-oauth-scopes": [] } }, "/v2/allowlists/{service}": { "get": { "operationId": "AllowlistsController_getAllowlist", "parameters": [ { "name": "service", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllowlistOutput" } } } } }, "summary": "Get the Cal.com IP allowlist of one service", "tags": ["Allowlists"], "x-oauth-scopes": [] } }, "/v2/api-keys/refresh": { "post": { "description": "Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization header (e.g. \"Authorization: Bearer \").", "operationId": "ApiKeysController_refresh", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshApiKeyInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshApiKeyOutput" } } } } }, "summary": "Refresh API Key", "tags": ["Api Keys"] } }, "/v2/bookings": { "post": { "description": "\n POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except:\n If eventTypeId in the request body is id of a regular event, then regular booking is created.\n\n If it is an id of a recurring event type, then recurring booking is created.\n\n Meaning that the request bodies are equal but the outcome depends on what kind of event type it is with the goal of making it as seamless for developers as possible.\n\n For team event types it is possible to create instant meeting. To do that just pass `\"instant\": true` to the request body. If the event type has an instant meeting schedule, requests made outside it, or too close to its end for the meeting to fit, are rejected with a 400.\n\n The start needs to be in UTC aka if the timezone is GMT+2 in Rome and meeting should start at 11, then UTC time should have hours 09:00 aka without time zone.\n\n Finally, there are 2 ways to book an event type belonging to an individual user:\n 1. Provide `eventTypeId` in the request body.\n 2. Provide `eventTypeSlug` and `username` and optionally `organizationSlug` if the user with the username is within an organization.\n\n And 2 ways to book and event type belonging to a team:\n 1. Provide `eventTypeId` in the request body.\n 2. Provide `eventTypeSlug` and `teamSlug` and optionally `organizationSlug` if the team with the teamSlug is within an organization.\n\n If you are creating a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n For event types that have SMS reminders workflow, you need to pass the attendee's phone number in the request body via `attendee.phoneNumber` (e.g., \"+19876543210\" in international format). This is an optional field, but becomes required when SMS reminders are enabled for the event type. For the complete attendee object structure, see the [attendee object](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#body-attendee) documentation.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n ", "operationId": "BookingsController_2026_02_25_createBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Accepts different types of booking input: Standard Booking, Instant Booking, or Recurring Booking.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Standard Booking", "$ref": "#/components/schemas/CreateBookingInput_2024_08_13" }, { "title": "Instant Booking", "$ref": "#/components/schemas/CreateInstantBookingInput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/CreateRecurringBookingInput_2024_08_13" } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingOutput_2024_08_13" } } } } }, "summary": "Create a booking", "tags": ["Bookings"], "x-oauth-scopes": [] }, "get": { "description": "Cursor-based pagination. Pass the `pagination.nextCursor` from the previous response as the `cursor` query parameter to fetch the next page. Omit `cursor` to fetch the first page. `pagination.hasMore` is `false` and `pagination.nextCursor` is `null` when you've reached the last page.\n\nMust pass `cal-api-version: 2026-05-01` header.\n\n**`status` filters to a single status.** Pass one (e.g. `?status=upcoming`) or omit to walk all statuses. To list bookings across multiple statuses, issue parallel requests — one per status — and merge client-side.\n\nThe sort direction and the page-1 anchor are derived from `status`:\n\n| `status` | Sort | Walk direction | Page-1 anchor (uuid bound) |\n|---|---|---|---|\n| _(omitted)_ | `Booking.uuid DESC` | Backward from far-future | upper bound at year 2100 |\n| `upcoming` | `Booking.uuid ASC` | Forward in time | lower bound at `NOW() − 1h` |\n| `recurring` | `Booking.uuid ASC` | Forward in time | lower bound at `NOW() − 1h` |\n| `unconfirmed` | `Booking.uuid ASC` | Forward in time | lower bound at `NOW() − 1h` |\n| `past` | `Booking.uuid DESC` | Backward in time | upper bound at `NOW()` |\n| `cancelled` | `Booking.uuid DESC` | Backward from far-future | upper bound at year 2100 |\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.", "operationId": "BookingsController_2026_05_01_getBookings", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-05-01.", "required": true, "schema": { "type": "string", "example": "2026-05-01", "default": "2026-05-01" } }, { "name": "status", "required": false, "in": "query", "description": "Filter bookings by a single status. Pass one (e.g. `?status=upcoming`) or omit to walk all statuses ordered by `Booking.uuid DESC`. To list bookings across multiple statuses, issue parallel requests, one per status.", "schema": { "example": "upcoming", "type": "string", "enum": ["upcoming", "recurring", "past", "cancelled", "unconfirmed"] } }, { "name": "attendeeEmail", "required": false, "in": "query", "description": "Filter bookings by the attendee's email address.", "schema": { "example": "example@domain.com", "type": "string" } }, { "name": "attendeeName", "required": false, "in": "query", "description": "Filter bookings by the attendee's name.", "schema": { "example": "John Doe", "type": "string" } }, { "name": "bookingUid", "required": false, "in": "query", "description": "Filter bookings by the booking Uid.", "schema": { "example": "2NtaeaVcKfpmSZ4CthFdfk", "type": "string" } }, { "name": "eventTypeIds", "required": false, "in": "query", "description": "Filter bookings by event type ids. Event type ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?eventTypeIds=100,200", "type": "string" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter bookings by event type id.", "schema": { "example": "?eventTypeId=100", "type": "string" } }, { "name": "teamsIds", "required": false, "in": "query", "description": "Filter bookings by team ids that user is part of. Team ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?teamIds=50,60", "type": "string" } }, { "name": "teamId", "required": false, "in": "query", "description": "Filter bookings by team id that user is part of", "schema": { "example": "?teamId=50", "type": "string" } }, { "name": "afterStart", "required": false, "in": "query", "description": "Filter bookings with start after this date string.", "schema": { "example": "?afterStart=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeEnd", "required": false, "in": "query", "description": "Filter bookings with end before this date string.", "schema": { "example": "?beforeEnd=2025-03-07T11:00:00.000Z", "type": "string" } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created after this date string.", "schema": { "example": "?afterCreatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created before this date string.", "schema": { "example": "?beforeCreatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated after this date string.", "schema": { "example": "?afterUpdatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated before this date string.", "schema": { "example": "?beforeUpdatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortCreated", "required": false, "in": "query", "description": "Sort results by their creation time (when booking was made) in ascending or descending order.", "schema": { "example": "?sortCreated=asc OR ?sortCreated=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort results by their updated time (for example when booking status changes) in ascending or descending order.", "schema": { "example": "?sortUpdatedAt=asc OR ?sortUpdatedAt=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "example": "eyJ2IjoxLCJzb3J0VXVpZCI6IjAxOGY0YzJlLTNmMWEtN2FiYy05ZGVmLTAxMjM0NTY3ODlhYiJ9", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingsOutput_2026_05_01" } } } } }, "summary": "Get all bookings", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/bookings/by-seat/{seatUid}": { "get": { "description": "Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and want to retrieve the full booking details.\n\n Cancelled seats remain resolvable by the same seatUid: the parent booking is returned and the matching attendee is tagged with status `cancelled`. Only that attendee is listed — remaining live attendees are not mixed in. Occupied-seat counts on GET /bookings/:uid are unchanged.\n\n A seat reschedule that keeps the same seatUid still resolves from the live row.\n\n If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n ", "operationId": "BookingsController_2026_02_25_getBookingBySeatUid", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "seatUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingOutput_2024_08_13" } } } } }, "summary": "Get a booking by seat UID", "tags": ["Bookings"], "x-oauth-scopes": [] } }, "/v2/bookings/{bookingUid}": { "get": { "description": "`:bookingUid` can be\n\n 1. uid of a normal booking\n\n 2. uid of one of the recurring booking recurrences\n\n 3. uid of recurring booking which will return an array of all recurring booking recurrences (stored as recurringBookingUid on one of the individual recurrences).\n\n If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n ", "operationId": "BookingsController_2026_02_25_getBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingOutput_2024_08_13" } } } } }, "summary": "Get a booking", "tags": ["Bookings"], "x-mcp": { "name": "get_booking", "guidance": "Get a specific booking by its UID (use get_bookings to find UIDs). Returns full details including attendees, location, and metadata." }, "x-oauth-scopes": [] } }, "/v2/bookings/{bookingUid}/recordings": { "get": { "description": "Fetches all the recordings for the booking `:bookingUid`. Requires authentication and proper authorization. Access is granted to the booking organizer and hosts, and to team or organization members whose role can view the booking and has the `booking.readRecordings` permission, which team and organization admins and owners have by default.\n\n \n Recording download links are valid for 1 hour only. Make a new request to generate fresh links after expiration.\n\n cal-api-version: `2026-02-25` is required in the request header.\n \n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.\n ", "operationId": "BookingsController_2026_02_25_getBookingRecordings", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingRecordingsOutput" } } } }, "429": { "description": "Rate limit exceeded. Please try again. The `Retry-After` response header carries the number of seconds to wait before retrying." } }, "summary": "Get all the recordings for the booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/bookings/{bookingUid}/transcripts": { "get": { "description": "Fetches all the transcript download links for the booking `:bookingUid`. Requires authentication and proper authorization. Access is granted to the booking organizer and hosts, and to team or organization members whose role can view the booking and has the `booking.readRecordings` permission, which team and organization admins and owners have by default.\n\n \n Transcripts are generated when clicking \"Transcribe\" during a Cal Video meeting, or from live captions in a Cal Video 2.0 meeting. Download links are valid for 1 hour only - make a new request to generate fresh links after expiration.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n \n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.\n ", "operationId": "BookingsController_2026_02_25_getBookingTranscripts", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingTranscriptsOutput" } } } }, "429": { "description": "Conferencing provider rate limit exceeded. Try again later. The `Retry-After` response header carries the number of seconds to wait before retrying." } }, "summary": "Get Cal Video real time transcript download links for the booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/bookings/{bookingUid}/reschedule": { "post": { "description": "Reschedule a booking or seated booking.\n\n Reschedulable booking statuses:\n - `accepted` — the confirmed booking is moved to the new start time.\n - `pending` — a booking awaiting host confirmation can be rescheduled. The new booking stays `pending` until the host confirms or declines it.\n\n Non-reschedulable booking statuses (endpoint responds with `400 Bad Request`):\n - `cancelled` — the booking has already been cancelled. If it was cancelled because it was previously rescheduled, the error message includes the UID of the booking it was rescheduled to.\n - `rejected` — the host declined the original confirmation-required request. Create a new booking instead.\n - `awaiting_host` — an instant meeting that is live and waiting for a host to join. Create a new booking instead.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n ", "operationId": "BookingsController_2026_02_25_rescheduleBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Accepts different types of reschedule booking input: Standard or Recurring Booking, or Seated Booking. If you're rescheduling a seated booking as org admin of booking host, pass booking input for Standard or Recurring Booking along with your access token in the request header.\n\n If you are rescheduling a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Standard or Recurring Booking", "$ref": "#/components/schemas/RescheduleBookingInput_2024_08_13" }, { "title": "Seated Booking", "$ref": "#/components/schemas/RescheduleSeatedBookingInput_2024_08_13" } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleBookingOutput_2024_08_13" } } } } }, "summary": "Reschedule a booking", "tags": ["Bookings"], "x-oauth-scopes": [] } }, "/v2/bookings/{bookingUid}/cancel": { "post": { "description": ":bookingUid can be :bookingUid of an usual booking, individual recurrence or recurring booking to cancel all recurrences.\n\n \nCancelling normal bookings:\n If the booking is not seated and not recurring, simply pass :bookingUid in the request URL `/bookings/:bookingUid/cancel` and optionally cancellationReason in the request body `{\"cancellationReason\": \"Will travel\"}`.\n\n \nCancelling seated bookings:\n It is possible to cancel specific seat within a booking as an attendee or all of the seats as the host.\n \n1. As an attendee - provide :bookingUid in the request URL `/bookings/:bookingUid/cancel` and seatUid in the request body `{\"seatUid\": \"123-123-123\"}` . This will remove this particular attendance from the booking.\n \n2. As the host or org admin of host - host can cancel booking for all attendees aka for every seat, this also applies to org admins. Provide :bookingUid in the request URL `/bookings/:bookingUid/cancel` and cancellationReason in the request body `{\"cancellationReason\": \"Will travel\"}` and `Authorization: Bearer token` request header where token is event type owner (host) credential. This will cancel the booking for all attendees.\n\n \nCancelling recurring seated bookings:\n For recurring seated bookings it is not possible to cancel all of them with 1 call\n like with non-seated recurring bookings by providing recurring bookind uid - you have to cancel each recurrence booking by its bookingUid + seatUid.\n\n If you are cancelling a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n ", "operationId": "BookingsController_2026_02_25_cancelBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Accepts different types of cancel booking input: Standard or Recurring Booking (for normal or recurring bookings) or Seated Booking (for seated bookings)", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Standard or Recurring Booking", "$ref": "#/components/schemas/CancelBookingInput_2024_08_13" }, { "title": "Seated Booking", "$ref": "#/components/schemas/CancelSeatedBookingInput_2024_08_13" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBookingOutput_2024_08_13" } } } } }, "summary": "Cancel a booking", "tags": ["Bookings"], "x-oauth-scopes": [] } }, "/v2/bookings/{bookingUid}/mark-absent": { "post": { "description": "The provided authorization header refers to the owner of the booking.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_markNoShow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAbsentBookingInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAbsentBookingOutput_2024_08_13" } } } } }, "summary": "Mark a booking absence", "tags": ["Bookings"], "x-mcp": { "name": "mark_booking_absent", "guidance": "Mark host or attendees as absent for a past booking. Set host=true if the host was absent. Use get_booking_attendees to look up real attendee emails before calling this.", "hints": { "idempotent": true } }, "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/reassign": { "post": { "description": "Reassigns the host of a round robin or managed event type booking. The provided authorization header refers to the owner of the booking.\n\n Without `userUuid` in the body, an available round robin host is picked automatically.\n\n With `userUuid`, the booking is reassigned to that user. For a **round robin** booking, the user must be one of the booking's hosts and the booking keeps its `uid`. For a **managed event** booking, the user must be one of the users the managed event is assigned to — list them, along with their availability for the booking's slot, with `GET /v2/bookings/{bookingUid}/reassignment-candidates`. Reassignment moves the booking onto the new host's own child event type, so the original booking is cancelled and **the returned booking has a new `uid`** which you must store in place of the old one. Recurring managed bookings cannot be reassigned yet.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_reassignBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignBookingInput_2026_02_25" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignBookingOutput_2026_02_25" } } } } }, "summary": "Reassign a booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/reassign/{userId}": { "post": { "description": "Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_reassignBookingToUser", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignToUserBookingInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignBookingOutput_2024_08_13" } } } } }, "summary": "Reassign a booking to a specific host", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/confirm": { "post": { "description": "The provided authorization header refers to the owner of the booking.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_confirmBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingOutput_2024_08_13" } } } } }, "summary": "Confirm a booking", "tags": ["Bookings"], "x-mcp": { "name": "confirm_booking", "guidance": "Confirm a pending booking that requires manual confirmation. Only the host can confirm.", "hints": { "idempotent": true } }, "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/seats/confirm": { "post": { "description": "Confirm selected seats on a booking whose event type requires confirmation and has seats. The authorization header refers to a host who can update the booking.\n\n`confirmedSeatUids` lists seats that were waiting and are now confirmed. Seats that were already confirmed stay confirmed and are omitted.\n\n`POST /v2/bookings/:bookingUid/confirm` refuses these bookings. Pass each seat's `seatUid` here instead.\n\nAvailable with `cal-api-version` `2024-08-13`, `2026-02-25`, and `2026-05-01`.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_confirmBookingSeats", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmBookingSeatsInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmBookingSeatsOutput_2024_08_13" } } } } }, "summary": "Confirm booking seats", "tags": ["Bookings"], "x-mcp": { "name": "confirm_booking_seats", "guidance": "Confirm selected pending seats on a confirmation-required seated booking. Pass seatUids from the booking. POST /bookings/{bookingUid}/confirm refuses these bookings.", "hints": { "idempotent": true } }, "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/seats/decline": { "post": { "description": "Decline selected seats on a booking whose event type requires confirmation and has seats. The authorization header refers to a host who can update the booking.\n\n`declinedSeatUids` lists seats that were waiting or confirmed and are now declined. Seats that were already declined stay declined and are omitted. A confirmed seat can be declined. An optional `reason` is stored on each declined seat and included in its decline email and booking-rejected workflow.\n\n`POST /v2/bookings/:bookingUid/decline` refuses these bookings. Pass each seat's `seatUid` here instead.\n\nAvailable with `cal-api-version` `2024-08-13`, `2026-02-25`, and `2026-05-01`.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_declineBookingSeats", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineBookingSeatsInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineBookingSeatsOutput_2024_08_13" } } } } }, "summary": "Decline booking seats", "tags": ["Bookings"], "x-mcp": { "name": "decline_booking_seats", "guidance": "Decline selected seats on a confirmation-required seated booking. Waiting and confirmed seats can be declined. Pass seatUids from the booking. An optional reason is stored on each declined seat. POST /bookings/{bookingUid}/decline refuses these bookings.", "hints": { "idempotent": true } }, "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/decline": { "post": { "description": "The provided authorization header refers to the owner of the booking.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_declineBooking", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineBookingInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingOutput_2024_08_13" } } } } }, "summary": "Decline a booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/request-reschedule": { "post": { "description": "Request to reschedule a booking. The booking will be cancelled and the attendee will receive an email with a link to reschedule.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingsController_2026_02_25_requestReschedule", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestRescheduleInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestRescheduleOutput_2024_08_13" } } } } }, "summary": "Request to reschedule a booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/calendar-links": { "get": { "description": "Retrieve calendar links for a booking that can be used to add the event to various calendar services. Returns links for Google Calendar, Microsoft Office, Microsoft Outlook, and a downloadable ICS file.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.\n ", "operationId": "BookingsController_2026_02_25_getCalendarLinks", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarLinksOutput_2024_08_13" } } } } }, "summary": "Get 'Add to Calendar' links for a booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/bookings/{bookingUid}/references": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.", "operationId": "BookingsController_2026_02_25_getBookingReferences", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter booking references by type", "schema": { "example": "google_calendar", "type": "string", "enum": [ "google_calendar", "office365_calendar", "daily_video", "google_video", "office365_video", "zoom_video" ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReferencesOutput_2024_08_13" } } } } }, "summary": "Get booking references", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_READ"], "x-platform-plan": "SCALE" } }, "/v2/bookings/{bookingUid}/conferencing-sessions": { "get": { "description": "Requires authentication and proper authorization. Access is granted to the booking organizer and hosts, and to team or organization members whose role can view the booking and has the `booking.readRecordings` permission, which team and organization admins and owners have by default.\n\n cal-api-version: `2026-02-25` is required in the request header.\n\n This endpoint is rate-limited to 60 requests per minute per caller (per API key, access token, OAuth client, or IP). Exceeding the limit returns a 429 response and blocks further calls for 60 seconds.\n\n If the upstream conferencing provider rate-limits the request, this endpoint responds with HTTP 429 and a `Retry-After` header carrying the number of seconds to wait before retrying. Clients should honor this hint.\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.", "operationId": "BookingsController_2026_02_25_getVideoSessions", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-02-25.", "required": true, "schema": { "type": "string", "example": "2026-02-25", "default": "2026-02-25" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingVideoSessionsOutput" } } } }, "429": { "description": "Rate limit exceeded — either the per-caller throttle or the upstream conferencing provider. The `Retry-After` response header carries the number of seconds to wait before retrying." } }, "summary": "Get Video Meeting Sessions. Only supported for Cal Video", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/bookings/{bookingUid}/location": { "patch": { "description": "Updates the booking location in Cal.com and updates the corresponding calendar event via the organizer's connected credentials. For integration locations (e.g. Zoom, Google Meet, Cal Video), the endpoint also provisions a conference link. Attendees and hosts are notified of the location change by email; set `notifyHosts` to false to skip the host emails.\n \n The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.", "operationId": "BookingLocationController_2024_08_13_updateBookingLocation", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.", "required": true, "schema": { "type": "string", "example": "2024-08-13" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingLocationInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingLocationOutput_2024_08_13" } } } } }, "summary": "Update booking location for an existing booking", "tags": ["Bookings"], "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/verification/email/send-code": { "post": { "description": "Sends a one-time verification code to the specified email address.", "operationId": "BookingsVerificationController_sendEmailVerificationCode", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendVerificationEmailInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendVerificationEmailOutput" } } } } }, "summary": "Send email verification code", "tags": ["Bookings - Email Verification"], "x-oauth-scopes": [] } }, "/v2/bookings/verification/email/check": { "get": { "description": "Checks whether email verification is required for the given email. Returns true if verification is needed.", "operationId": "BookingsVerificationController_checkEmailVerificationRequired", "parameters": [ { "name": "email", "required": true, "in": "query", "schema": { "example": "user@example.com", "type": "string" } }, { "name": "userSessionEmail", "required": false, "in": "query", "schema": { "example": "user@example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Check if email verification is required", "tags": ["Bookings - Email Verification"], "x-oauth-scopes": [] } }, "/v2/bookings/verification/email/verify-code": { "post": { "description": "Verifies an email address using the one-time code that was previously sent.", "operationId": "BookingsVerificationController_verifyEmailCode", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailCodeInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailCodeOutput" } } } } }, "summary": "Verify email with code", "tags": ["Bookings - Email Verification"], "x-oauth-scopes": [] } }, "/v2/bookings/{bookingUid}/attendees": { "get": { "description": "Retrieve all attendees for a specific booking by its UID.\n \n The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.\n ", "operationId": "BookingAttendeesController_2024_08_13_getBookingAttendees", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.", "required": true, "schema": { "type": "string", "example": "2024-08-13" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingAttendeesOutput_2024_08_13" } } } } }, "summary": "Get all attendees for a booking", "tags": ["Bookings / Attendees"], "x-mcp": { "name": "get_booking_attendees", "guidance": "Get all attendees for a booking by its UID." }, "x-oauth-scopes": ["BOOKING_READ"] }, "post": { "description": "Add a new attendee to an existing booking by its UID.\n\n **Seated Events:**\n This endpoint does not support seated event bookings. For seated events, each attendee must be added by creating a new booking for the same event type and time slot via `POST /v2/bookings`. Attempting to add an attendee to a seated event booking will return a 400 error.\n\n **Side effects:**\n - The booking's attendee list is updated in the database\n - The calendar event is updated on connected calendars (Google Calendar, Outlook, etc.) to include the new attendee\n - An email notification is sent to the new attendee with the booking details\n\n **Permissions:**\n - The authenticated user must be either the booking organizer, an existing attendee, or have the `booking.update` permission for the team\n\n The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingAttendeesController_2024_08_13_addAttendee", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.", "required": true, "schema": { "type": "string", "example": "2024-08-13" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAttendeeInput_2024_08_13" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAttendeeOutput_2024_08_13" } } } } }, "summary": "Add an attendee to a booking", "tags": ["Bookings / Attendees"], "x-mcp": { "name": "add_booking_attendee", "guidance": "Add a new attendee to an existing booking. Required: name, email, timeZone. ASK THE USER for all attendee details — never guess or fabricate names, emails, or time zones." }, "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/attendees/{attendeeId}": { "get": { "description": "Retrieve a specific attendee by their ID for a booking identified by its UID.\n \n The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.\n ", "operationId": "BookingAttendeesController_2024_08_13_getBookingAttendee", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.", "required": true, "schema": { "type": "string", "example": "2024-08-13" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "attendeeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingAttendeeOutput_2024_08_13" } } } } }, "summary": "Get a specific attendee for a booking", "tags": ["Bookings / Attendees"], "x-mcp": { "name": "get_booking_attendee", "guidance": "Get a specific attendee by their numeric ID within a booking. Use get_booking_attendees to find attendee IDs." }, "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/bookings/{bookingUid}/guests": { "post": { "description": "Add one or more guests to an existing booking. Maximum 10 guests per request, with a limit of 30 total guests per booking.\n \n **Contacts:**\n Pass `contactIds` or `contactTagIds` to add the authenticated user's own contacts by id, or every contact with one of their tags, instead of typing their emails. Typed guests, contacts and tagged contacts are combined once per email, ignoring case. A contact or tag the user doesn't own is a 400, and a tag that doesn't fit the booking is refused whole.\n \n **Rate Limiting:**\n This endpoint is rate limited to 5 requests per minute to prevent abuse.\n \n **Seated Events:**\n This endpoint does not support seated event bookings. For seated events, each guest must be added by creating a new booking for the same event type and time slot via `POST /v2/bookings`. Attempting to add guests to a seated event booking will return a 400 error.\n \n **Email Notifications:**\n When guests are added, the following notifications are sent (unless disabled by event type settings):\n \n - **Organizer & Team Members:** Receive an \"Add Guests\" notification email informing them that new guests have been added to the booking.\n \n - **New Guests:** Receive a \"Scheduled Event\" email with full booking details and calendar invite. If they have a phone number, they also receive an SMS notification.\n \n - **Existing Guests:** Receive an \"Add Guests\" notification email informing them that additional guests have been added to the booking.\n \n The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.\n\nIf accessed using an OAuth access token, the `BOOKING_WRITE` scope is required.\n ", "operationId": "BookingGuestsController_2024_08_13_addGuests", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.", "required": true, "schema": { "type": "string", "example": "2024-08-13" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGuestsInput_2024_08_13" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGuestsOutput_2024_08_13" } } } } }, "summary": "Add guests to an existing booking", "tags": ["Bookings / Guests"], "x-oauth-scopes": ["BOOKING_WRITE"] } }, "/v2/bookings/{bookingUid}/routing-trace": { "get": { "description": "Retrieve the step-by-step routing trace for a booking identified by its UID. Shows how the booking was routed through routing forms, CRM lookups, and host selection logic.\n\nReturns presented (human-readable) trace steps grouped by routing round, along with the routing form submission if one was used.\n\nIf no routing trace exists for the booking, empty steps and groups are returned.\n\nThe cal-api-version header is required for this endpoint.\n\nIf accessed using an OAuth access token, the `BOOKING_READ` scope is required.\n ", "operationId": "BookingRoutingTraceController_2024_08_13_getBookingRoutingTrace", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-08-13` or later.", "required": true, "schema": { "type": "string", "example": "2024-08-13" } }, { "name": "bookingUid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingRoutingTraceOutput_2024_08_13" } } } } }, "summary": "Get the routing trace for a booking", "tags": ["Bookings / Routing Trace"], "x-mcp": { "name": "get_booking_routing_trace", "guidance": "Get the routing trace for a booking — the step-by-step decision path showing how the booking was routed (routing form evaluation, CRM lookups, host selection). Returns human-readable steps grouped by round, plus the routing form submission answers. Only available for bookings that completed routing (permanent traces). Use get_bookings to find booking UIDs." }, "x-oauth-scopes": ["BOOKING_READ"] } }, "/v2/calendars/{calendar}/event/{eventUid}": { "get": { "description": "Returns detailed information about a meeting including attendance metrics. If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "CalUnifiedCalendarsController_getCalendarEventDetails", "parameters": [ { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["google"], "type": "string" } }, { "name": "eventUid", "required": true, "in": "path", "description": "The Google Calendar event ID. You can retrieve this by getting booking references from the following endpoints:\n\n- For team events: https://cal.com/docs/api-reference/v2/orgs-teams-bookings/get-booking-references-for-a-booking\n\n- For user events: https://cal.com/docs/api-reference/v2/bookings/get-booking-references-for-a-booking", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUnifiedCalendarEventOutput" } } } } }, "summary": "Get meeting details from calendar", "tags": ["Cal Unified Calendars"], "x-oauth-scopes": ["APPS_READ"] } }, "/v2/calendars/{calendar}/events/{eventUid}": { "patch": { "description": "Updates event information in the specified calendar provider. If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "CalUnifiedCalendarsController_updateCalendarEvent", "parameters": [ { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["google"], "type": "string" } }, { "name": "eventUid", "required": true, "in": "path", "description": "The Google Calendar event ID. You can retrieve this by getting booking references from the following endpoints:\n\n- For team events: https://cal.com/docs/api-reference/v2/orgs-teams-bookings/get-booking-references-for-a-booking\n\n- For user events: https://cal.com/docs/api-reference/v2/bookings/get-booking-references-for-a-booking", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUnifiedCalendarEventInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUnifiedCalendarEventOutput" } } } } }, "summary": "Update meeting details in calendar", "tags": ["Cal Unified Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/calendars/ics-feed/save": { "post": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "CalendarsController_createIcsFeed", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIcsFeedInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIcsFeedOutputResponseDto" } } } } }, "summary": "Save an ICS feed", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/calendars/ics-feed/check": { "get": { "description": "If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "CalendarsController_checkIcsFeed", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Check an ICS feed", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_READ"] } }, "/v2/calendars/busy-times": { "get": { "description": "Get busy times from a calendar. Example request URL is `https://api.cal.com/v2/calendars/busy-times?timeZone=Europe%2FMadrid&dateFrom=2024-12-18&dateTo=2024-12-18&calendar=135,skrauciz%40gmail.com&calendar=200,bob%40gmail.com`.\n\nThe `calendar` query parameter identifies one calendar as `,`, e.g. `calendar=135,alice@example.com`. Both values are returned for each connected calendar by `GET /v2/calendars`. To load busy times from multiple calendars, pass the `calendar` query parameter multiple times, e.g. `calendar=135,alice@example.com&calendar=200,bob@example.com`. Only the first comma separates the two values, so an `externalId` containing commas is kept intact.\n\nNote: loggedInUsersTz is deprecated, use timeZone instead. If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "CalendarsController_getBusyTimes", "parameters": [ { "name": "loggedInUsersTz", "required": false, "in": "query", "deprecated": true, "description": "Deprecated: Use timeZone instead. The timezone of the user represented as a string", "schema": { "example": "America/New_York", "type": "string" } }, { "name": "timeZone", "required": false, "in": "query", "description": "The timezone for the busy times query represented as a string", "schema": { "example": "America/New_York", "type": "string" } }, { "name": "dateFrom", "required": true, "in": "query", "description": "The starting date for the busy times query", "schema": { "example": "2023-10-01", "type": "string" } }, { "name": "dateTo", "required": true, "in": "query", "description": "The ending date for the busy times query", "schema": { "example": "2023-10-31", "type": "string" } }, { "name": "calendar", "required": false, "in": "query", "description": "Calendar to load busy times from, formatted as credentialId,externalId. Repeat the parameter to load multiple calendars, e.g. calendar=135,alice@example.com&calendar=200,bob@example.com. At least one calendar is required.", "schema": { "example": ["135,alice@example.com"], "type": "array", "items": { "type": "string", "pattern": "^\\d+,.+$" } } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBusyTimesOutput" } } } } }, "summary": "Get busy times", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_READ"] } }, "/v2/calendars": { "get": { "description": "If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "CalendarsController_getCalendars", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedCalendarsOutput" } } } } }, "summary": "Get all calendars", "tags": ["Calendars"], "x-mcp": { "name": "get_connected_calendars", "guidance": "List all calendar integrations connected to the authenticated user's account. Returns each calendar's credentialId and externalId, which are required by get_busy_times. Also shows the user's destination calendar." }, "x-oauth-scopes": ["APPS_READ"] } }, "/v2/calendars/{calendar}/connect": { "get": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "CalendarsController_redirect", "parameters": [ { "name": "Authorization", "required": true, "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "schema": { "type": "string" } }, { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["office365", "google"], "type": "string" } }, { "name": "isDryRun", "required": true, "in": "query", "schema": { "type": "boolean" } }, { "name": "redir", "required": false, "in": "query", "description": "Redirect URL after successful calendar authorization.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Get OAuth connect URL", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/calendars/{calendar}/save": { "get": { "operationId": "CalendarsController_save", "parameters": [ { "name": "state", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["office365", "google"], "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Save Google or Outlook calendar credentials", "tags": ["Calendars"], "x-oauth-scopes": [] } }, "/v2/calendars/{calendar}/credentials": { "post": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "CalendarsController_syncCredentials", "parameters": [ { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["apple"], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCalendarCredentialsInput" } } } }, "responses": { "201": { "description": "" } }, "summary": "Save Apple calendar credentials", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/calendars/{calendar}/check": { "get": { "description": "If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "CalendarsController_check", "parameters": [ { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["apple", "google", "office365"], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Check a calendar connection", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_READ"] } }, "/v2/calendars/{calendar}/disconnect": { "post": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "CalendarsController_deleteCalendarCredentials", "parameters": [ { "name": "calendar", "required": true, "in": "path", "schema": { "enum": ["apple", "google", "office365"], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCalendarCredentialsInputBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedCalendarCredentialsOutputResponseDto" } } } } }, "summary": "Disconnect a calendar", "tags": ["Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/conferencing/{app}/connect": { "post": { "description": "Only `google-meet` can be connected this way, and only for a user who already has a valid Google Calendar connection. Zoom and Microsoft Teams require an OAuth handshake - start it with `GET /v2/conferencing/{app}/oauth/auth-url` instead. Walkthrough: https://cal.com/docs/api-reference/v2/conferencing-apps. If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "ConferencingController_connect", "parameters": [ { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["google-meet"], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferencingAppOutputResponseDto" } } } } }, "summary": "Connect your conferencing application", "tags": ["Conferencing"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/conferencing/{app}/oauth/auth-url": { "get": { "description": "Returns the URL to send the user to so they can authorize Zoom or Microsoft Teams. Redirect the user's browser to it - the provider then returns them to a callback already registered by Cal.com, which stores the credential against the owner of the access token that started the flow. `returnTo` and `onErrorReturnTo` must each be a relative path or an absolute http(s) URL. The returned URL expires 10 minutes after this call, so redirect immediately rather than caching it. Walkthrough: https://cal.com/docs/api-reference/v2/conferencing-apps. If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "ConferencingController_redirect", "parameters": [ { "name": "Authorization", "required": true, "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "schema": { "type": "string" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["zoom", "msteams"], "type": "string" } }, { "name": "returnTo", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "onErrorReturnTo", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConferencingAppsOauthUrlResponseDto" } } } } }, "summary": "Get OAuth conferencing app auth URL", "tags": ["Conferencing"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/conferencing/{app}/oauth/callback": { "get": { "operationId": "ConferencingController_save", "parameters": [ { "name": "state", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["zoom", "msteams"], "type": "string" } }, { "name": "code", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Conferencing app OAuth callback", "tags": ["Conferencing"], "x-oauth-scopes": [] } }, "/v2/conferencing": { "get": { "description": "If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "ConferencingController_listInstalledConferencingApps", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferencingAppsOutputResponseDto" } } } } }, "summary": "List your conferencing applications", "tags": ["Conferencing"], "x-mcp": { "name": "get_conferencing_apps", "guidance": "List all conferencing applications connected to the authenticated user's account (e.g. Zoom, Google Meet, Cal Video)." }, "x-oauth-scopes": ["APPS_READ"] } }, "/v2/conferencing/{app}/default": { "post": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "ConferencingController_default", "parameters": [ { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["google-meet", "zoom", "msteams", "daily-video"], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultConferencingAppOutputResponseDto" } } } } }, "summary": "Set your default conferencing application", "tags": ["Conferencing"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/conferencing/default": { "get": { "description": "If accessed using an OAuth access token, the `APPS_READ` scope is required.", "operationId": "ConferencingController_getDefault", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDefaultConferencingAppOutputResponseDto" } } } } }, "summary": "Get your default conferencing application", "tags": ["Conferencing"], "x-oauth-scopes": ["APPS_READ"] } }, "/v2/conferencing/{app}/disconnect": { "delete": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "ConferencingController_disconnect", "parameters": [ { "name": "app", "required": true, "in": "path", "description": "Conferencing application type", "schema": { "enum": ["google-meet", "zoom", "msteams"], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectConferencingAppOutputResponseDto" } } } } }, "summary": "Disconnect your conferencing application", "tags": ["Conferencing"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/contacts": { "get": { "description": "Returns the authenticated user's personal contacts from their Contacts page, ordered by stored name (nulls last), email and id, with limit/cursor pagination. `tagIds` narrows the list to contacts carrying at least one of the tags. When pagination.hasMore is true, pass pagination.nextCursor as cursor with the same search and tagIds. Use usernames of contacts with groupBooking eligible for dynamic group availability and booking with the authenticated user. Team and organization members are not included. A contact whose email belongs to a verified, discoverable Cal account shows that account's name, username and booking page. Contact avatars and Cal user ids are never returned. If accessed using an OAuth access token, the `CONTACT_READ` scope is required.", "operationId": "ContactsController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Part of a contact's name or email, to narrow the list.", "schema": { "maxLength": 100, "example": "jamie", "type": "string" } }, { "name": "tagIds", "required": false, "in": "query", "description": "Tag ids from `GET /v2/contacts/tags`, to list only contacts carrying at least one of them. Separate ids with commas, or repeat the parameter once per id.", "schema": { "maxItems": 100, "example": ["0192f3a1-7c2b-7d4e-9a10-00000000000a", "0192f3a1-7c2b-7d4e-9a10-00000000000b"], "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of contacts to return.", "schema": { "minimum": 1, "maximum": 50, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from pagination.nextCursor. Omit for the first page; keep the same search and tagIds on subsequent pages.", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsOutputResponseDto" } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many contact lookups" } }, "summary": "List personal contacts", "tags": ["Contacts"], "x-mcp": { "name": "list_contacts", "guidance": "List the user's personal contacts from their Contacts page, up to 50 per page, narrowed by search and by tagIds to contacts carrying at least one of the tags; when pagination.hasMore is true, pass pagination.nextCursor as cursor with the same search and tagIds. Each contact has its id, name, email and tags. A contact on Cal (type calUser) also has their username, bookingUrl and groupBooking: eligible when they can join a dynamic group meeting with the user, outsideOrganization when they are in another organization, unavailable otherwise. Use eligible contacts' usernames for group availability and booking. Team and organization members, avatars and Cal user ids are never returned." }, "x-oauth-scopes": ["CONTACT_READ"] }, "post": { "description": "Adds a personal contact to the authenticated user's Contacts page by email, with an optional name. The email is checked for its format and mail server first, and a user holds at most 5,000 contacts. Adding an email already in the user's contacts changes nothing, not even its name. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactsController_add", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactOutputResponseDto" } } } }, "400": { "description": "The email failed the format or mail server check" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "409": { "description": "The user already has 5,000 contacts" }, "429": { "description": "Too many contacts added" } }, "summary": "Add a personal contact", "tags": ["Contacts"], "x-mcp": { "name": "add_contact", "guidance": "Add a personal contact to the user's Contacts page by email, with an optional name. The email is checked for its format and mail server first, and a user holds at most 5,000 contacts. Adding an email already in the user's contacts changes nothing, not even its name.", "hints": { "idempotent": true } }, "x-oauth-scopes": ["CONTACT_WRITE"] } }, "/v2/contacts/tags": { "get": { "description": "Returns the authenticated user's own tags, the ones they can put on their contacts, ordered by name and id, with limit/cursor pagination. Each tag has how many of the user's contacts carry it. They are the same personal tags the user can put on their own links; team tags are not included. When pagination.hasMore is true, pass pagination.nextCursor as cursor. If accessed using an OAuth access token, the `CONTACT_READ` scope is required.", "operationId": "ContactsController_listTags", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of tags to return.", "schema": { "minimum": 1, "maximum": 50, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "The pagination.nextCursor value from the previous page. Omit for the first page.", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactTagsOutputResponseDto" } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many tag lookups" } }, "summary": "List contact tags", "tags": ["Contacts"], "x-mcp": { "name": "list_contact_tags", "guidance": "List the user's own tags, the ones they can put on their contacts, sorted by name, up to 50 per page; when pagination.hasMore is true, pass pagination.nextCursor as cursor. Each tag has its id, name and contactCount, how many of the user's contacts carry it. They are the same personal tags the user can put on their own links; team tags are never listed." }, "x-oauth-scopes": ["CONTACT_READ"] }, "post": { "description": "Creates one of the authenticated user's own tags, to put on their contacts with `POST /v2/contacts/{id}/tags`. The tag is personal, never a team's, and it is also offered for the user's own links. It does not put the tag on any contact. A name the user already has is refused. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactsController_createTag", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactTagInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactTagOutputResponseDto" } } } }, "400": { "description": "The name or color is not allowed" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "409": { "description": "The user already has a tag with this name" }, "429": { "description": "Too many tags created" } }, "summary": "Create a contact tag", "tags": ["Contacts"], "x-mcp": { "name": "create_contact_tag", "guidance": "Create one of the user's own tags, to put on their contacts. Returns the new tag's id and name. A name the user already has is refused. The tag is personal, never a team's, and it is also offered for the user's own links. It does not put the tag on any contact." }, "x-oauth-scopes": ["CONTACT_WRITE"] } }, "/v2/contacts/{id}": { "patch": { "description": "Updates one of the authenticated user's personal contacts, changing only the fields given in the body; a body with no fields changes nothing and returns the contact as it is. `name` is the only field today. A contact on Cal (`type: calUser`) shows the name from their Cal account and can't have its name changed. A contact the user does not have is not found. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The contact's `id` from `GET /v2/contacts`.", "schema": { "example": "0192f3a1-7c2b-7d4e-9a10-000000000001", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactOutputResponseDto" } } } }, "400": { "description": "The contact is on Cal, or the name is not allowed" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Contact not found" } }, "summary": "Update a personal contact", "tags": ["Contacts"], "x-mcp": { "name": "update_contact", "guidance": "Update one of the user's personal contacts; today that is only its name. A contact on Cal shows the name from their Cal account, and its name cannot be changed. A contact the user does not have is not found." }, "x-oauth-scopes": ["CONTACT_WRITE"] }, "delete": { "description": "Removes one of the authenticated user's personal contacts, with its tags. It cannot be undone: adding the email again makes a new contact, without the old one's tags. A contact the user does not have is not found. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The contact's `id` from `GET /v2/contacts`.", "schema": { "example": "0192f3a1-7c2b-7d4e-9a10-000000000001", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactOutputResponseDto" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Contact not found" } }, "summary": "Remove a personal contact", "tags": ["Contacts"], "x-mcp": { "name": "remove_contact", "guidance": "Remove one of the user's personal contacts, with its tags. It cannot be undone. A contact the user does not have is not found." }, "x-oauth-scopes": ["CONTACT_WRITE"] } }, "/v2/contacts/{id}/tags": { "post": { "description": "Puts one of the authenticated user's own tags on one of their contacts. The contact keeps every other tag, and a tag it already carries is left as it is. A team tag, another user's tag or an unknown id is refused. A contact the user does not have is not found. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactsController_addTag", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The contact's `id` from `GET /v2/contacts`.", "schema": { "example": "0192f3a1-7c2b-7d4e-9a10-000000000001", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContactTagInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTagChangeOutputResponseDto" } } } }, "400": { "description": "The tag is not the user's own" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Contact not found" }, "429": { "description": "Too many contact lookups" } }, "summary": "Add a tag to a contact", "tags": ["Contacts"], "x-mcp": { "name": "add_contact_tag", "guidance": "Put one of the user's own tags on one of their contacts. The contact keeps every other tag, and a tag it already carries is left as it is. A team tag, another user's tag or an unknown id is refused. A contact the user does not have is not found.", "hints": { "idempotent": true } }, "x-oauth-scopes": ["CONTACT_WRITE"] } }, "/v2/contacts/{id}/tags/{tagId}": { "delete": { "description": "Takes one tag off one of the authenticated user's contacts. The contact keeps every other tag, and a tag it does not carry changes nothing. The tag itself is not deleted. A contact the user does not have is not found. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactsController_removeTag", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The contact's `id` from `GET /v2/contacts`.", "schema": { "example": "0192f3a1-7c2b-7d4e-9a10-000000000001", "type": "string" } }, { "name": "tagId", "required": true, "in": "path", "description": "The tag's `id` from the contact's `tags`.", "schema": { "example": "0192f3a1-7c2b-7d4e-9a10-00000000000a", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTagChangeOutputResponseDto" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Contact not found" }, "429": { "description": "Too many contact lookups" } }, "summary": "Remove a tag from a contact", "tags": ["Contacts"], "x-mcp": { "name": "remove_contact_tag", "guidance": "Take one tag off one of the user's contacts. The contact keeps every other tag, and a tag it does not carry changes nothing. The tag itself is not deleted, so add_contact_tag can put it back. A contact the user does not have is not found.", "hints": { "destructive": false, "idempotent": true } }, "x-oauth-scopes": ["CONTACT_WRITE"] } }, "/v2/contacts/suggestions": { "get": { "description": "Returns people the authenticated user keeps meeting but hasn't added as personal contacts: attendees of at least 4 accepted, past bookings the user hosted in the last 12 months. Existing contacts, the user's own emails, dismissed suggestions and blocked emails are left out. Ordered by meeting count, then most recent meeting, with limit/cursor pagination; when pagination.hasMore is true, pass pagination.nextCursor as cursor. To accept a suggestion, add it with `POST /v2/contacts` using its email and name. To hide it for good, dismiss it with `POST /v2/contacts/suggestions/dismissals`. If accessed using an OAuth access token, the `CONTACT_READ` scope is required.", "operationId": "ContactSuggestionsController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of suggestions to return.", "schema": { "minimum": 1, "maximum": 50, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from pagination.nextCursor. Omit for the first page.", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactSuggestionsOutputResponseDto" } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many contact lookups" } }, "summary": "List suggested contacts", "tags": ["Contacts"], "x-oauth-scopes": ["CONTACT_READ"] } }, "/v2/contacts/suggestions/dismissals": { "post": { "description": "Stops suggesting an email to the authenticated user, for good. Dismissing an email that was already dismissed, or that isn't suggested, changes nothing. It does not add or remove a personal contact; to accept a suggestion instead, use `POST /v2/contacts`. If accessed using an OAuth access token, the `CONTACT_WRITE` scope is required.", "operationId": "ContactSuggestionsController_dismiss", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissContactSuggestionInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissContactSuggestionOutputResponseDto" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many contact lookups" } }, "summary": "Dismiss a suggested contact", "tags": ["Contacts"], "x-oauth-scopes": ["CONTACT_WRITE"] } }, "/v2/credits/available": { "get": { "description": "Check if the authenticated user (or their org/team) has available credits and return the current balance. Third-party OAuth tokens require the `CREDITS_READ` scope.", "operationId": "CreditsController_getAvailableCredits", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Check available credits", "tags": ["Credits"], "x-oauth-scopes": ["CREDITS_READ"] } }, "/v2/credits/charge": { "post": { "description": "Charge up to 10,000 credits with a covering balance. Team and organization charges require manageBilling permission. References are scoped to the caller; replays return charged: false and duplicate: true. Third-party OAuth tokens require the `CREDITS_WRITE` scope.", "operationId": "CreditsController_chargeCredits", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeCreditsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Charge credits", "tags": ["Credits"], "x-oauth-scopes": ["CREDITS_WRITE"] } }, "/v2/oauth-clients/{clientId}/users": { "get": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientUsersController_getManagedUsers", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 250, "example": 10, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "The number of items to skip", "schema": { "minimum": 0, "maximum": 250, "example": 0, "type": "number" } }, { "name": "emails", "required": false, "in": "query", "description": "Filter managed users by email. If you want to filter by multiple emails, separate them with a comma.", "schema": { "minItems": 1, "example": "?emails=email1@example.com,email2@example.com", "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedUsersOutput" } } } } }, "summary": "Get all managed users", "tags": ["Deprecated: Platform / Managed Users"] }, "post": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientUsersController_createUser", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedUserInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedUserOutput" } } } } }, "summary": "Create a managed user", "tags": ["Deprecated: Platform / Managed Users"] } }, "/v2/oauth-clients/{clientId}/users/{userId}": { "get": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientUsersController_getUserById", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedUserOutput" } } } } }, "summary": "Get a managed user", "tags": ["Deprecated: Platform / Managed Users"] }, "patch": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientUsersController_updateUser", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateManagedUserInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedUserOutput" } } } } }, "summary": "Update a managed user", "tags": ["Deprecated: Platform / Managed Users"] }, "delete": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientUsersController_deleteUser", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedUserOutput" } } } } }, "summary": "Delete a managed user", "tags": ["Deprecated: Platform / Managed Users"] } }, "/v2/oauth-clients/{clientId}/users/{userId}/force-refresh": { "post": { "description": "These endpoints are deprecated and will be removed in the future. If you have lost managed user access or refresh token, then you can get new ones by using OAuth credentials. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields.\nResponse also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields.", "operationId": "OAuthClientUsersController_forceRefresh", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysResponseDto" } } } } }, "summary": "Force refresh tokens", "tags": ["Deprecated: Platform / Managed Users"] } }, "/v2/oauth/{clientId}/refresh": { "post": { "description": "These endpoints are deprecated and will be removed in the future. If managed user access token is expired then get a new one using this endpoint - it will also refresh the refresh token, because we use\n \"refresh token rotation\" mechanism. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields.\nResponse also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields.", "operationId": "OAuthFlowController_refreshTokens", "parameters": [ { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "required": true, "in": "header", "description": "OAuth client secret key.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysResponseDto" } } } } }, "summary": "Refresh managed user tokens", "tags": ["Deprecated: Platform / Managed Users"] } }, "/v2/oauth-clients/{clientId}/webhooks": { "post": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientWebhooksController_createOAuthClientWebhook", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientWebhookOutputResponseDto" } } } } }, "summary": "Create a webhook", "tags": ["Deprecated: Platform / Webhooks"] }, "get": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientWebhooksController_getOAuthClientWebhooks", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientWebhooksOutputResponseDto" } } } } }, "summary": "Get all webhooks", "tags": ["Deprecated: Platform / Webhooks"] }, "delete": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientWebhooksController_deleteAllOAuthClientWebhooks", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteManyWebhooksOutputResponseDto" } } } } }, "summary": "Delete all webhooks", "tags": ["Deprecated: Platform / Webhooks"] } }, "/v2/oauth-clients/{clientId}/webhooks/{webhookId}": { "patch": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientWebhooksController_updateOAuthClientWebhook", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInputDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientWebhookOutputResponseDto" } } } } }, "summary": "Update a webhook", "tags": ["Deprecated: Platform / Webhooks"] }, "get": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientWebhooksController_getOAuthClientWebhook", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientWebhookOutputResponseDto" } } } } }, "summary": "Get a webhook", "tags": ["Deprecated: Platform / Webhooks"] }, "delete": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientWebhooksController_deleteOAuthClientWebhook", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "OAuth client secret key", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientWebhookOutputResponseDto" } } } } }, "summary": "Delete a webhook", "tags": ["Deprecated: Platform / Webhooks"] } }, "/v2/oauth-clients": { "post": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientsController_createOAuthClient", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthClientInput" } } } }, "responses": { "201": { "description": "Create an OAuth client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthClientResponseDto" } } } } }, "summary": "Create an OAuth client", "tags": ["Deprecated: Platform OAuth Clients"] }, "get": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientsController_getOAuthClients", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOAuthClientsResponseDto" } } } } }, "summary": "Get all OAuth clients", "tags": ["Deprecated: Platform OAuth Clients"] } }, "/v2/oauth-clients/{clientId}": { "get": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientsController_getOAuthClientById", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOAuthClientResponseDto" } } } } }, "summary": "Get an OAuth client", "tags": ["Deprecated: Platform OAuth Clients"] }, "patch": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientsController_updateOAuthClient", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthClientInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOAuthClientResponseDto" } } } } }, "summary": "Update an OAuth client", "tags": ["Deprecated: Platform OAuth Clients"] }, "delete": { "description": "These endpoints are deprecated and will be removed in the future.", "operationId": "OAuthClientsController_deleteOAuthClient", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOAuthClientResponseDto" } } } } }, "summary": "Delete an OAuth client", "tags": ["Deprecated: Platform OAuth Clients"] } }, "/v2/destination-calendars": { "put": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "DestinationCalendarsController_updateDestinationCalendars", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationCalendarsInputBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationCalendarsOutputResponseDto" } } } } }, "summary": "Update destination calendars", "tags": ["Destination Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/discover/listings": { "get": { "description": "Returns published Discover listings by id, with the fields their public cards show: service name, provider, price, new-client discount, the provider's rating, review count and verification, duration, whether it is online, city, neighborhood and the business's time zone. With `includeNextAvailable`, also the earliest open slot in the next 7 days for the first 10 listings. Any id that is not a published listing is returned in `notFoundListingIds`. Requests with `includeNextAvailable` are limited to 60 per minute per user, shared across all of the user's API keys and access tokens. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "DiscoverListingsController_getListings", "parameters": [ { "name": "ids", "required": true, "in": "query", "description": "Discover listing ids, such as the `listingId` values a Discover search returned. Repeat the parameter (`ids=12&ids=34`) or separate the ids with commas (`ids=12,34`). Duplicates are read once.", "schema": { "minItems": 1, "maxItems": 50, "example": [12, 34], "type": "array", "items": { "type": "integer", "maximum": 2147483647, "minimum": 1 } } }, { "name": "includeNextAvailable", "required": false, "in": "query", "description": "Also look up each listing's earliest open slot in the next 7 days. Only the first 10 listings are checked, so list the ones you care about first.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDiscoverListingsOutputResponseDto" } } } }, "400": { "description": "ids is missing, has more than 50 ids or a non-positive id" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many listing lookups with this credential, or more than 60 `includeNextAvailable` requests per minute for this user across all of their credentials" } }, "summary": "Get Discover listings by id", "tags": ["Discover"], "x-mcp": { "name": "get_discover_listings", "guidance": "Read published Discover listings by id, as their public cards show them: service name, provider, price, new-client discount, rating, review count, verified, duration, whether it is online, city and neighborhood, and optionally the earliest open slot in the next 7 days for the first 10. An id that is not a published listing is returned as not found." }, "x-oauth-scopes": ["EVENT_TYPE_READ"] } }, "/v2/discover/listings/search": { "get": { "description": "Searches the published Discover listings the way Cal.ai does. In-person results stay within the area you name, else around your saved ZIP code; with neither, nothing is searched and `areaNeeded` is returned. When the named area or the saved ZIP code cannot be found, nothing is searched and `areaNeeded` comes with `areaNotFound`. Online-only categories and `onlineOnly` searches are searched everywhere. An empty neighborhood widens to its whole region (`widenedFrom`); an empty search retries with the category alone (`broadenedFrom`); when the whole area has nothing, the web is searched there once and businesses not on Discover come back in `webBusinesses`. Availability is judged in your saved time zone. Searches are limited to 20 per minute per user, and web searches to 10 per hour per user, each shared across all of the user's API keys and access tokens; past the web search limit a search still returns its listings, without `webBusinesses`. The web search runs on your own AI access: when one of your organizations has turned AI off, it is skipped and the listings still return. A place lookup that is rate limited answers 429 and one that fails answers 503, each with a message starting `Place lookup`; neither means the place does not exist. Other 429s are the request limits above. Each result's `bookingUrl` is attributed to Discover. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "DiscoverListingSearchController_searchListings", "parameters": [ { "name": "category", "required": false, "in": "query", "description": "The Discover category the need maps to, such as `medical` for tooth pain.", "schema": { "example": "barbers", "type": "string", "enum": [ "medical", "barbers", "coaching", "consulting", "lessons", "pets", "sports", "dance", "social", "online-services", "saas", "home-services", "other" ] } }, { "name": "subcategory", "required": false, "in": "query", "description": "A subcategory of `category`, such as `dentistry` under `medical`. Ignored without its category, and named in `ignoredFilters` when it is not one of the category's.", "schema": { "example": "haircuts", "type": "string", "enum": [ "dentistry", "therapy", "physiotherapy", "nutrition", "somatic-and-breathwork", "doula", "general-care", "haircuts", "beard-and-shave", "coloring", "kids-cuts", "nails", "waxing", "lashes", "skin-and-spa", "massage", "tattoo", "life", "career", "executive", "mindset", "spiritual", "business", "tech-and-ai", "finance-and-tax", "legal", "real-estate", "marketing", "hr", "academic", "language", "music-and-voice", "arts", "chess", "veterinary", "grooming", "training", "sitting", "fitness", "yoga", "tennis", "swimming", "skiing", "salsa", "ballet", "hip-hop", "ballroom", "clubs", "workshops", "networking", "tours", "photoshoots-and-studios", "pop-ups-and-showrooms", "design", "development", "writing", "virtual-assistance", "legal-advice", "product-demos", "onboarding", "customer-support", "sales", "cleaning", "repairs", "heating-and-cooling", "inspections", "auto" ] } }, { "name": "query", "required": false, "in": "query", "description": "Free text matched against the title, description, provider and subcategory. Never a place.", "schema": { "maxLength": 100, "example": "skin fade", "type": "string" } }, { "name": "neighborhood", "required": false, "in": "query", "description": "A neighborhood of a launch region, such as `Capitol Hill`, for in-person listings there only. An unknown name comes back in `ignoredFilters`.", "schema": { "maxLength": 80, "example": "Capitol Hill", "type": "string" } }, { "name": "onlineOnly", "required": false, "in": "query", "description": "Keep only online listings and search them everywhere, whatever `area` says. Online searches never fall back to the web.", "schema": { "example": false, "type": "boolean" } }, { "name": "localQuery", "required": false, "in": "query", "description": "For the web fallback, the need in the area's local language when it is not English, such as `Zahnarzt` for a dentist in Hamburg.", "schema": { "maxLength": 100, "example": "Zahnarzt", "type": "string" } }, { "name": "area", "required": false, "in": "query", "description": "The place to search around: a ZIP code, neighborhood or city. Without it, the search uses your saved ZIP code, and answers `areaNeeded` when there is none. Pass `anywhere` for results from anywhere.", "schema": { "maxLength": 80, "example": "98122", "type": "string" } }, { "name": "maximumPrice", "required": false, "in": "query", "description": "The highest price, in whole currency units: 50 means $50, 0 means free only.", "schema": { "minimum": 0, "example": 50, "type": "number" } }, { "name": "maximumDurationMinutes", "required": false, "in": "query", "description": "The longest session, in minutes.", "schema": { "minimum": 1, "example": 60, "type": "number" } }, { "name": "availableWithin", "required": false, "in": "query", "description": "Only listings with a real open slot in this window, in your saved time zone. `this_week` means the next 7 days.", "schema": { "example": "today", "type": "string", "enum": ["today", "tomorrow", "this_week"] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchDiscoverListingsOutputResponseDto" } } } }, "400": { "description": "A query parameter is not one the search accepts" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "One of three limits, told apart by the error message: this credential's request throttle or this user's limit of 20 searches per minute across all of their credentials (both `… Too many requests …`), or the place lookup's own limit (`Place lookup rate limited …`). Back off and retry later; only the last means the place lookup failed." }, "503": { "description": "The place lookup is unavailable for the moment (`Place lookup unavailable …`). The place was not rejected; retry the same search later." } }, "summary": "Search Discover listings", "tags": ["Discover"], "x-mcp": { "name": "search_listings", "guidance": "Search the published Discover listings: bookable services with provider, price, duration, rating, neighborhood, distance, next open slot and the listing's booking page. Filter by category, subcategory, free text, neighborhood, area, maximum price, maximum duration and an availability window. In-person results stay within the searched area; online-only categories are searched everywhere." }, "x-oauth-scopes": ["EVENT_TYPE_READ"] } }, "/v2/discover/business-calls": { "post": { "description": "Has Cal's voice assistant call a business on the user's behalf to book the service, the way Cal.ai does once the user approves. Only a business that `GET /v2/discover/listings/search` returned in `webBusinesses` to this same user in the last 24 hours can be called, with its URL exactly as returned; a Discover listing is never called, because it is booked from its `bookingUrl`. Every check runs before the call: the account may place calls, the business's page offers a US or Canadian appointment phone, the name and service are plain words, the business was not called too recently, and the user's plan covers it. The call is placed by Cal's AI voice assistant, so a user in an organization that opted out of AI cannot place calls. A call that is not placed answers `placed: false` with the `reason`. A refusal spends neither daily limit, except a refusal for calling hours found after Cal set up the call, which keeps that business's count for the day. If dialling fails after the call was started, the user's call is given back when the provider refused the dial, but that business's count for the day is not; a dial whose outcome is unknown counts against both, since the business may have been rung. A placed call answers with `callUrl`, the call's page, where the user follows the call and its outcome. Calls are limited to 5 a day per user, shared across all of the user's API keys and access tokens, and to 10 a day per business across all users. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required.", "operationId": "DiscoverBusinessCallsController_callBusiness", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDiscoverBusinessInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDiscoverBusinessOutputResponseDto" } } } }, "400": { "description": "The body is not one the call accepts" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many calls with this credential, or more than 5 calls today for this user across all of their credentials. Retry later." } }, "summary": "Call a web-found business to book", "tags": ["Discover"], "x-mcp": { "name": "call_business_to_book", "guidance": "Call an allowlisted web-found business to book a service on the user's behalf after the user approves. Uses the exact business URL from Discover search and only the appointment phone the business's page offers; never for a Discover listing." }, "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/discover/booking-jobs": { "post": { "description": "Has Cal's booking agent book a service on a business's own online booking page for the user, the way Cal.ai does once the user approves. Only a business that `GET /v2/discover/listings/search` returned in `webBusinesses` to this same user in the last 24 hours can be booked, with its URL exactly as returned; a Discover listing is never booked this way, because it is booked from its `bookingUrl`. Every check runs before the job starts: the account may book online, has a username, has fewer than the allowed number of jobs running, and its plan covers the booking. The booking agent browses with AI, so a user in an organization that opted out of AI cannot book online. A job that is not started answers `created: false` with the `reason` and spends no budget. A started job answers with `jobUrl`, the job's page, where the user picks an appointment option, approves the price and terms, or cancels: this API never chooses or approves anything. Every request carries an `idempotencyKey` the client generates once per booking; send the same key to retry the same request and get the same job back without spending the budget again, even after the business's allowlist entry expired or its page went down; a deployment that cannot run jobs on Trigger.dev answers `created: false`. Jobs are limited to 3 an hour per user, shared across all of the user's API keys and access tokens. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required.", "operationId": "DiscoverBookingJobsController_createBookingJob", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDiscoverBookingJobInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDiscoverBookingJobOutputResponseDto" } } } }, "400": { "description": "The body is not one the booking agent accepts" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many requests with this credential, or more than 3 jobs this hour for this user across all of their credentials. Retry later." } }, "summary": "Book a web-found business online", "tags": ["Discover"], "x-mcp": { "name": "book_online", "guidance": "Start a booking on an allowlisted web-found business's own online booking page through Cal's booking agent after the user approves. The agent then shows the appointment options, price, terms and any deposit for the user to approve; never for a Discover listing." }, "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/discover/service-requests": { "post": { "description": "Records that the authenticated user is looking for a service Discover has no listing for, so they are emailed at their account address when a matching provider joins. Asking again for the same need within 90 days returns the open request only in the same region: a repeat in another region, or with a `searchedArea` where there was none (or none where there was one), records a new request. `matchedProviders` in the response says which new providers can trigger the email: only online ones, or none, when the request is outside every launch region, so pass the `searchedArea` of the user's search. The response never includes the request's id, an email address or who else asked. Limited to 10 requests per hour per user, shared across all of the user's API keys and access tokens. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required.", "operationId": "DiscoverServiceRequestsController_record", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordDiscoverServiceRequestInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordDiscoverServiceRequestOutputResponseDto" } } } }, "400": { "description": "The service is empty, longer than 80 characters or can't be recorded, or the category is unknown" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "429": { "description": "Too many requests with this credential, or more than 10 service requests per hour for this user across all of their credentials" } }, "summary": "Ask to be told when a Discover provider joins", "tags": ["Discover"], "x-mcp": { "name": "record_service_request", "guidance": "Record that the user is looking for a service Discover has no listing for, so they are emailed at their account address when a matching provider joins. Asking again for the same need in the same area returns the open request rather than a second one; in another area, or with no area after one, it records a new request." }, "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/event-type-sequences/{uid}": { "get": { "description": "What a booker sees before booking the sequence: its segments in order, who each collective segment is with, and the questions asked once for the whole sequence. No authentication is required. A sequence that can't be booked right now is not found.", "operationId": "EventTypeSequencesController_getPublic", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "uid", "required": true, "in": "path", "description": "The sequence's `uid`.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEventTypeSequenceResponseOutput" } } } } }, "summary": "Get a sequence's booking page", "tags": ["Event Type Sequences"], "x-oauth-scopes": [] } }, "/v2/event-type-sequences/{uid}/slots": { "get": { "description": "The times at which the whole sequence can be booked: every segment fits its own hosts, notice and booking window, back to back. Each start time is when the first segment begins. No authentication is required, and each caller can make 60 requests a minute. A sequence that can't be booked right now returns no start times.", "operationId": "EventTypeSequencesController_getSlots", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "uid", "required": true, "in": "path", "description": "The sequence's `uid`.", "schema": { "format": "uuid", "type": "string" } }, { "required": true, "description": "\n Time starting from which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to start of day or specify hours:\n 2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z\n ", "name": "start", "in": "query", "schema": { "example": "2033-09-05", "type": "string" } }, { "required": true, "description": "\n Time until which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to end of day or specify hours:\n 2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z", "name": "end", "in": "query", "schema": { "example": "2033-09-06", "type": "string" } }, { "required": false, "description": "Time zone in which the available slots should be returned. Defaults to UTC.", "name": "timeZone", "in": "query", "schema": { "example": "Europe/Rome", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSequenceSlotsResponseOutput" } } } } }, "summary": "Get a sequence's available start times", "tags": ["Event Type Sequences"], "x-oauth-scopes": [] } }, "/v2/event-types/{eventTypeId}/calendar-invites": { "get": { "description": "Returns host and guest invite-description settings resolved from the event type, organization default when the mode is `inherit`, then Cal.com's standard description. Access matches reading the event type; OAuth clients require `EVENT_TYPE_READ`. Custom templates are limited to 5,000 characters. Managed children inherit their parent's templates and are marked read-only. Host templates are private and are not included in event-type responses.", "operationId": "EventTypesController_2026_06_12_getEventTypeCalendarInvites", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCalendarInvitesOutput" } } } } }, "summary": "Get event-type calendar-invite templates", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_READ"] }, "patch": { "description": "Updates host and/or guest settings without changing other event-type fields; omitted audiences remain unchanged. `inherit` uses the organization default, `standard` uses Cal.com's standard description, and `custom` uses a supplied template of at most 5,000 characters. HTML tags are stripped and Markdown links are kept. Managed children are read-only and return HTTP 400; update their parent. Access matches updating the event type; OAuth clients require `EVENT_TYPE_WRITE`.", "operationId": "EventTypesController_2026_06_12_updateEventTypeCalendarInvites", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarInvitesInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCalendarInvitesOutput" } } } } }, "summary": "Update event-type calendar-invite templates", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/event-types": { "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section.\n\nIf `bookingFields` is omitted, the event type is created with its default booking fields. At least one contact field—`email` or `attendeePhoneNumber`—must remain visible and required. Other default fields, such as additional notes, can be hidden. Provide `bookingFields` to customize the default fields or add custom booking fields. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_createEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventTypeInput_2026_06_12" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventTypeOutput_2026_06_12" } } } } }, "summary": "Create an event type", "tags": ["Event Types"], "x-mcp": { "name": "create_event_type", "guidance": "Create a new event type. Required: title, slug, lengthInMinutes. Supports locations, booking fields, buffers, recurrence, confirmation policy, seats, and more." }, "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nHidden event types and hidden booking fields are returned only when listing your own event types. Other callers see public event types and visible booking fields.", "operationId": "EventTypesController_2026_06_12_getEventTypes", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "username", "required": false, "in": "query", "description": "The username of the user to get event types for. If only username provided will get all event types.", "schema": { "type": "string" } }, { "name": "eventSlug", "required": false, "in": "query", "description": "Slug of event type to return. Notably, if eventSlug is provided then username must be provided too, because multiple users can have event with same slug.", "schema": { "type": "string" } }, { "name": "usernames", "required": false, "in": "query", "description": "Get dynamic event type for multiple usernames separated by comma. e.g `usernames=alice,bob`", "schema": { "type": "string" } }, { "name": "orgSlug", "required": false, "in": "query", "description": "slug of the user's organization if he is in one, orgId is not required if using this parameter", "schema": { "type": "string" } }, { "name": "orgId", "required": false, "in": "query", "description": "ID of the organization of the user you want the get the event-types of, orgSlug is not needed when using this parameter", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort event types by creation date. When not provided, no explicit ordering is applied.", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypesOutput_2026_06_12" } } } } }, "summary": "List event types", "tags": ["Event Types"], "x-mcp": { "name": "get_event_types", "guidance": "List event types. Without parameters returns all event types for the authenticated user. Pass 'username' to list another user's event types, or username + eventSlug for a specific one. Use usernames (comma-separated) for dynamic group event types." }, "x-oauth-scopes": [] } }, "/v2/event-types/{eventTypeId}/history": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.\n\nOnly the event type owner and applicable administrators can view its history. General event type read access does not include access to its history.", "operationId": "EventTypesController_2026_06_12_getEventTypeHistory", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of audit logs to return. Defaults to 25 and cannot exceed 50.", "schema": { "minimum": 1, "maximum": 50, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous response. Pass `pagination.nextCursor` to fetch the next page of audit logs.", "schema": { "maxLength": 2048, "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJpZCI6IjAxSFgifQ", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeHistoryOutput_2024_06_14" } } } } }, "summary": "Get event type history", "tags": ["Event Types"], "x-mcp": { "name": "get_event_type_history", "guidance": "Get the audit history (change log) for an event type by ID (use get_event_types to find IDs). Returns audit log entries showing what changed, who made the change, when, and the previous/new field values, ordered most recent first. Supports cursor pagination via limit (1-50, default 25) and cursor. Requires audit-history access to the event type — general read access alone is not sufficient." }, "x-oauth-scopes": ["EVENT_TYPE_READ"] } }, "/v2/event-types/{eventTypeId}/scheduling-config": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nThe response varies by the event type's scheduling type, and non-team event types are rejected.\n\nIf accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypesController_2026_06_12_getSchedulingConfig", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulingConfigOutput" } } } } }, "summary": "Get scheduling configuration", "tags": ["Event Types"], "x-mcp": { "name": "get_scheduling_config", "guidance": "Get the scheduling configuration for a team event type. For roundRobin types: returns hosts (with priority, weight, mandatory status, group assignment), host groups, distribution settings (maxLeadThreshold), and advanced settings (weights enabled, no-show calculation, CRM fallback). For collective/managed types: returns hosts with basic info and assignAllTeamMembers. The event type must be a team event type — returns 422 otherwise." }, "x-oauth-scopes": ["EVENT_TYPE_READ"] } }, "/v2/event-types/{eventTypeId}/crm-sync-errors": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nBy default, only active CRM sync errors are returned; pass `includeDismissed=true` to include dismissed errors.\n\nIf accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypesController_2026_06_12_getCrmSyncErrors", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "appSlug", "required": true, "in": "query", "description": "CRM app slug connected to the event type, for example `salesforce`.", "schema": { "example": "salesforce", "type": "string" } }, { "name": "includeDismissed", "required": false, "in": "query", "description": "When true, returns dismissed historical errors as well as active errors. Defaults to false.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from `pagination.nextCursor`. Omit to fetch the first page of CRM sync errors.", "schema": { "example": "eyJ2IjoxLCJzb3J0VXVpZCI6IjAxOWVhODUwLWVmYzctN2E0OC04NTA4LWFlZDMxYjcyY2U2OCJ9", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of CRM sync errors to return.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCrmSyncErrorsOutput_2024_06_14" } } } } }, "summary": "List CRM sync errors for an event type", "tags": ["Event Types"], "x-mcp": { "name": "get_crm_sync_errors", "guidance": "List CRM sync errors for an event type and CRM app slug, such as salesforce. By default returns active/current errors only; set includeDismissed=true to include dismissed historical errors. Use eventTypeId plus appSlug, not credentialId. Supports cursor pagination via limit (1-100, default 50) and cursor. Requires read access to the event type." }, "x-oauth-scopes": ["EVENT_TYPE_READ"] } }, "/v2/event-types/{eventTypeId}": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReturns hidden booking fields only to callers who are allowed to view them. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypesController_2026_06_12_getEventTypeById", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "integer" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeOutput_2026_06_12" } } } } }, "summary": "Get an event type", "tags": ["Event Types"], "x-mcp": { "name": "get_event_type", "guidance": "Get a specific event type by its numeric ID or UUID (use get_event_types to find IDs). Returns full details including locations, booking fields, and schedule." }, "x-oauth-scopes": ["EVENT_TYPE_READ"] }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nOmit `bookingFields` to keep the existing booking fields. If provided, the array replaces them, and any omitted default fields are restored with their default settings. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_updateEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventTypeInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventTypeOutput_2026_06_12" } } } } }, "summary": "Update an event type", "tags": ["Event Types"], "x-mcp": { "name": "update_event_type", "guidance": "Update an existing event type by ID (use get_event_types to find IDs). Any provided field replaces the current value. Array fields (locations, bookingFields) replace entirely — fetch the current event type first with get_event_type to avoid losing existing values." }, "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_deleteEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEventTypeOutput_2024_06_14" } } } } }, "summary": "Delete an event type", "tags": ["Event Types"], "x-mcp": { "name": "delete_event_type", "guidance": "Permanently delete an event type by ID. This action is irreversible — confirm with the user before proceeding." }, "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/event-types/{eventTypeId}/booking-fields": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReturns default and custom booking fields, plus any read-only workflow-added fields. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypesController_2026_06_12_getBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Get booking fields", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_READ"] }, "put": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReplaces all booking fields. Omitted custom fields are deleted, while omitted default fields are restored with their default settings. Use `PATCH` to update specific fields. Workflow-added fields are read-only and ignored. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_replaceBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Replace booking fields", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nAdds custom booking fields. Default and workflow-added fields cannot be added through this endpoint. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_createCustomBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsInput_2026_06_12" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Add custom booking fields", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nUpdates the booking fields identified by `slug`. Omitted properties keep their current values. Workflow-added fields are read-only. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_updateBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBookingFieldsInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Update booking fields", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/event-types/{eventTypeId}/booking-fields/{slug}": { "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nDeletes the custom booking field identified by `slug`. Default fields cannot be deleted, set hidden instead. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesController_2026_06_12_deleteCustomBookingField", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Delete a custom booking field", "tags": ["Event Types"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/event-types/{eventTypeId}/webhooks": { "post": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypeWebhooksController_createEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Create a webhook", "tags": ["Event Types / Webhooks"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "get": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypeWebhooksController_getEventTypeWebhooks", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhooksOutputResponseDto" } } } } }, "summary": "Get all webhooks", "tags": ["Event Types / Webhooks"], "x-oauth-scopes": ["EVENT_TYPE_READ"] }, "delete": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypeWebhooksController_deleteAllEventTypeWebhooks", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteManyWebhooksOutputResponseDto" } } } } }, "summary": "Delete all webhooks", "tags": ["Event Types / Webhooks"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/event-types/{eventTypeId}/webhooks/{webhookId}": { "patch": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypeWebhooksController_updateEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInputDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Update a webhook", "tags": ["Event Types / Webhooks"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "get": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypeWebhooksController_getEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Get a webhook", "tags": ["Event Types / Webhooks"], "x-oauth-scopes": ["EVENT_TYPE_READ"] }, "delete": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypeWebhooksController_deleteEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Delete a webhook", "tags": ["Event Types / Webhooks"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/event-types/{eventTypeId}/private-links": { "post": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesPrivateLinksController_2024_09_04_createPrivateLink", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrivateLinkInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrivateLinkOutput" } } } } }, "summary": "Create a private link for an event type", "tags": ["Event Types Private Links"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "get": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "EventTypesPrivateLinksController_2024_09_04_getPrivateLinks", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPrivateLinksOutput" } } } } }, "summary": "Get all private links for an event type", "tags": ["Event Types Private Links"], "x-oauth-scopes": ["EVENT_TYPE_READ"] } }, "/v2/event-types/{eventTypeId}/private-links/{linkId}": { "patch": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesPrivateLinksController_2024_09_04_updatePrivateLink", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "linkId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePrivateLinkBody" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePrivateLinkOutput" } } } } }, "summary": "Update a private link for an event type", "tags": ["Event Types Private Links"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] }, "delete": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "EventTypesPrivateLinksController_2024_09_04_deletePrivateLink", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to `2024-09-04`. Returns the full booking URL including org slug and event slug.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "linkId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePrivateLinkOutput" } } } } }, "summary": "Delete a private link for an event type", "tags": ["Event Types Private Links"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/events": { "get": { "description": "Returns the Events the authenticated user hosts: Events they own, plus Events they have accepted a co-host invitation to. A co-hosted Event may be owned by a team, so a team-owned Event can appear here — but team-owned Events the user neither hosts nor co-hosts are not returned by this endpoint; list those with `GET /v2/teams/{teamId}/events`. Ordered by start time, newest first when `status` is omitted.\n\nCursor-based pagination: pass `pagination.nextCursor` from a previous response as the `cursor` query parameter to fetch the next page; omit `cursor` for the first page. `pagination.hasMore` is `false` and `pagination.nextCursor` is `null` on the last page.\n\nMust pass `cal-api-version: 2026-05-01` (or later). Older versions use `take`/`skip` offset pagination.\n\nEvents are fixed-date RSVP pages served at cal.com/{slug}; they are not event types (bookable meeting templates) or calendar events. If accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventsController_listCursor", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "example": "eyJ2IjoyLCJzdGFydFRpbWUiOiIyMDMwLTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJldmVudFR5cGVVdWlkIjoiMDE4ZjRjMmUtM2YxYS03YWJjLTlkZWYtMDEyMzQ1Njc4OWFiIn0", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of Events to return.", "schema": { "minimum": 1, "maximum": 250, "default": 50, "example": 25, "type": "number" } }, { "name": "slug", "required": false, "in": "query", "description": "Filter by the event's public page slug (cal.com/{slug}).", "schema": { "example": "team-offsite", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter events by lifecycle status. `draft`: not published and not cancelled, ordered soonest first. `upcoming`: published and not yet ended, or cancelled but not yet started, ordered soonest first. `past`: everything else, ordered latest first. Omit to return all statuses, newest first. When provided, `pagination.nextCursor` encodes the status — cursors from one status value cannot be used with another and return 400.", "schema": { "example": "upcoming", "type": "string", "enum": ["draft", "upcoming", "past"] } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-05-01 (or a later API version) for cursor pagination.", "required": true, "schema": { "type": "string", "example": "2026-05-01", "default": "2026-05-01" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsCursorOutputResponseDto" } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" } }, "summary": "List Events (cursor pagination)", "tags": ["Events"], "x-mcp": { "name": "get_events", "guidance": "List the authenticated user's Cal Events: fixed-date RSVP pages served at cal.com/{slug}, such as a workshop or meetup that guests register for. Events are NOT event types (bookable meeting templates; use get_event_types) and NOT calendar events or bookings. Use this when the user asks about their Events or RSVP pages, or to find an Event's uuid for get_event. Returns Events the user owns or co-hosts, newest start time first; team-owned Events they do not host are not included. Supports limit (1-250, default 50) and filtering by slug; when pagination.hasMore is true, pass pagination.nextCursor as cursor to fetch the next page." }, "x-oauth-scopes": ["EVENT_READ"] }, "post": { "description": "Creates a draft Event for the authenticated user. A draft is not public and nobody can register until it is published with `POST /v2/events/{uuid}/publish`. To create an Event owned by a team, use `POST /v2/teams/{teamId}/events`.\n\n`startTime` and `endTime` are ISO 8601 in UTC; `startTime` must not be in the past and `endTime` must be after `startTime`.\n\n`guestList` controls whether guests see names, a count, or neither. `locations` sets where the Event happens; set `price` and `currency` on a location to charge for that place.\n\nEvents are fixed-date RSVP pages served at cal.com/{slug}; they are not event types (bookable meeting templates) or calendar events.\n\nLearn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventsController_create", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOutputResponseDto" } } } }, "400": { "description": "Invalid input, or a start time in the past" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" } }, "summary": "Create an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}": { "get": { "description": "Returns one Event by UUID. The authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. Events are fixed-date RSVP pages served at cal.com/{slug}; they are not event types (bookable meeting templates) or calendar events. If accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventsController_get", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Get an Event", "tags": ["Events"], "x-mcp": { "name": "get_event", "guidance": "Get one Cal Event (a fixed-date RSVP page served at cal.com/{slug}) by its uuid. Not for event types (use get_event_type with a numeric id) or calendar events. Use this when you already have the Event's uuid; otherwise call get_events first and never guess the uuid. An Event the user cannot access returns 404, the same as one that does not exist." }, "x-oauth-scopes": ["EVENT_READ"] }, "patch": { "description": "Updates the properties sent and leaves every other property as it is. Takes the same properties as `POST /v2/events` except `locations`, which have their own endpoints under `/v2/events/{uuid}/locations`.\n\n`hosts`, `liveStreams`, `registrationFields`, `lineup` and `schedule` replace the whole stored list. `lineup: null` removes the lineup. Pass `null` to `capacity` for unlimited guests.\n\nThe slug and the guest list can't change once the Event is published, and a cancelled Event can't be updated. New times must keep every schedule item inside the Event. An accepted co-host can update the Event but not its hosts, slug or policies such as `visibility`, `guestList` or `requiresApproval`.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventsController_update", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOutputResponseDto" } } } }, "400": { "description": "Invalid input, an end time that is not after the start time, new times that leave a schedule item outside the Event, a slug change after publishing, or a cancelled Event" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions, a guest list change after publishing, or a co-host changing the hosts, slug or policies" }, "404": { "description": "Event not found" } }, "summary": "Update an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] }, "delete": { "description": "Removes an Event, its registrations and its occurrence booking. An upcoming published Event is cancelled first, notifying its guests, and disappears from listings immediately; it is permanently removed once those notices have gone out. An Event cancelled more than seven days earlier is removed at once. An ended Event that still has confirmed guests cannot be deleted, and a published paid Event cannot be deleted because its payment records are retained. The authenticated user must be its owner, one of its hosts, or a member of the owning team; an external co-host gets 404. PBAC permission for team events: `calEvent.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventsController_delete", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEventOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, or the Event must be cancelled first" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Delete an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/publish": { "post": { "description": "Takes a draft Event live: its public page becomes reachable, guests can RSVP, the occurrence lands on the hosts' calendars. Idempotent for an Event that is already published. A cancelled Event cannot be published. The authenticated user must be its owner, one of its hosts, or a member of the owning team; an external co-host gets 404, exactly like an unknown uuid. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventsController_publish", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, a cancelled Event, or an Event that cannot be published as configured" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions, or the account must verify its email first" }, "404": { "description": "Event not found" } }, "summary": "Publish an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/cancel": { "post": { "description": "Cancels a published Event and notifies every registered guest; paid registrations are refunded. The Event stays listed with `cancelledAt` set. Drafts cannot be cancelled (delete them instead) and neither can Events that already ended. The authenticated user must be its owner, one of its hosts, or a member of the owning team; an external co-host gets 404. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventsController_cancel", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelEventInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, a draft, or an Event that already ended" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Cancel an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/bookings": { "get": { "description": "Returns the Event's guests in the statuses given by `status`, confirmed guests by default. A confirmed guest holds a seat on the Event's occurrence booking, the same way `GET /v2/bookings` reads attendees; pass `status=PENDING_APPROVAL` to list the guests waiting for approval, `WAITLISTED` for the waitlist, or `PENDING_PAYMENT` for guests who have not paid yet. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.read`. Cursor-based pagination: pass `pagination.nextCursor` from a previous response as the `cursor` query parameter to fetch the next page; omit `cursor` for the first page. If accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventRegistrationsController_listBookings", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of guests to return.", "schema": { "minimum": 1, "maximum": 250, "default": 50, "example": 25, "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by registration status. Separate several statuses with a comma. Defaults to confirmed guests only.", "schema": { "minItems": 1, "default": ["CONFIRMED"], "example": "?status=PENDING_APPROVAL,WAITLISTED", "type": "array", "items": { "type": "string", "enum": [ "PENDING_APPROVAL", "WAITLISTED", "PENDING_PAYMENT", "PENDING_CONFIRMATION", "OFFER_EXPIRED", "CONFIRMED", "DECLINED", "CANCELLED" ] } } }, { "name": "rsvpResponse", "required": false, "in": "query", "description": "Filter by the guest's RSVP response.", "schema": { "type": "string", "enum": ["YES", "NO", "MAYBE"] } }, { "name": "search", "required": false, "in": "query", "description": "Filter by guest name or email, case-insensitive substring match.", "schema": { "maxLength": 255, "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by the location the guest registered for.", "schema": { "maxLength": 128, "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBookingsOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, cursor or status" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "List an Event's bookings", "tags": ["Events"], "x-oauth-scopes": ["EVENT_READ"] } }, "/v2/events/{uuid}/registrations/{registrationId}/check-in": { "post": { "description": "Records a door check-in for one registration, the roster's manual tap (no QR involved). Same access as approving/declining guests — an external co-host may also work the door. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventRegistrationsController_checkInById", "parameters": [ { "name": "registrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInOutcomeOutputResponseDto" } } } }, "400": { "description": "Invalid Event or registration UUID, or check-in is closed" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or registration not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Check in a guest by registration id", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] }, "delete": { "description": "Clears a mistaken door check-in. Idempotent: undoing an unchecked registration is a no-op report. Not gated by the event's check-in window — undo corrects the host's own record rather than recording attendance. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventRegistrationsController_undoCheckIn", "parameters": [ { "name": "registrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoCheckInOutcomeOutputResponseDto" } } } }, "400": { "description": "Invalid Event or registration UUID" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or registration not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Undo a guest's check-in", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/check-ins": { "post": { "description": "Redeems a scanned check-in QR token. The token is carried in the request body, never the URL, since URLs land in history and access logs. Same access as the by-id check-in; an external co-host may also work the door. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventRegistrationsController_checkInByToken", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInByTokenInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInOutcomeOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, invalid token, or check-in is closed" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or registration not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Check in a guest by scanned QR token", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/registrations/approve-all": { "post": { "description": "Approves the Event's guests waiting for approval, optionally only those matching `search` or registered for `locationId`, as the roster's Approve all does. A free Event approves them in this request and returns `completed` with the counts. A paid Event sends each guest a payment request in the background and returns `started`. The Event must be published and not cancelled. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventRegistrationsController_approveAll", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAllRegistrationsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAllOutcomeOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or body, the Event is not open for registration, or too many pending guests" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Approve every pending guest", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/registrations/{registrationId}/approve": { "post": { "description": "Approves one guest waiting for approval, as the roster's Approve does. On a free Event the guest gets a seat and `kind` is `confirmed`; when the Event is full the guest stays pending and `kind` is `event_full_offer_waitlist`. On a paid Event the guest is sent a payment request and `kind` is `payment_pending`. The Event must be published and not cancelled. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventRegistrationsController_approve", "parameters": [ { "name": "registrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationDecisionOutcomeOutputResponseDto" } } } }, "400": { "description": "Invalid Event or registration UUID, the Event is not open for registration, or the guest is not waiting for approval" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or registration not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Approve a guest", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/registrations/{registrationId}/decline": { "post": { "description": "Declines one guest waiting for approval or on the waitlist, as the roster's Decline does, and emails them. `kind` is `declined`. A guest can be declined even when the Event is cancelled. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventRegistrationsController_decline", "parameters": [ { "name": "registrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationDecisionOutcomeOutputResponseDto" } } } }, "400": { "description": "Invalid Event or registration UUID, or the guest is not waiting for approval or on the waitlist" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or registration not found" } }, "summary": "Decline a guest", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/registrations/counts": { "get": { "description": "Returns how many of the Event's guests are in each status, how many answered each RSVP, how many are checked in and how many seats each location holds, as the roster's tabs show them. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.read`. If accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventRegistrationsController_counts", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationCountsOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Count an Event's guests", "tags": ["Events"], "x-oauth-scopes": ["EVENT_READ"] } }, "/v2/events/{uuid}/co-hosts": { "get": { "description": "Returns the Event's co-hosts in their display order, with pending and declined invitations alongside accepted co-hosts.\n\nCo-hosts are people invited by email to help run the Event without joining the owning team. Unlike hosts — the owner and the team members on the Event's host roster, who can do everything — an accepted co-host can view and edit the Event's details and manage its guests (invite, approve, check in), but cannot publish, cancel or delete the Event, change its pricing, or manage co-hosts. An invitation grants nothing until the invitee accepts it while signed in with the invited email address.\n\nThe authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team; an accepted co-host sees only the accepted co-hosts.\n\nPBAC permission for team events: `calEvent.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventCoHostsController_list", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoHostsOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "List an Event's co-hosts", "tags": ["Events"], "x-oauth-scopes": ["EVENT_READ"] }, "post": { "description": "Invites an email address to co-host the Event and emails it a link to accept, valid for 7 days. See `GET /v2/events/{uuid}/co-hosts` for what a co-host can do.\n\nThe new invitation joins the end of the co-host list; re-inviting an address that is already invited sends a fresh link and keeps its place, and re-inviting an accepted co-host changes nothing. Rate limited per user.\n\nThe authenticated user must be its owner, one of its hosts, or a member of the owning team; an accepted co-host cannot invite and gets 404, exactly like an unknown uuid.\n\nPBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventCoHostsController_invite", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCoHostInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCoHostOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, an invalid or undeliverable email address, or the caller's own address" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Invite a co-host to an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/co-hosts/order": { "patch": { "description": "Saves the display order of the Event's co-hosts. `coHostIds` must name every co-host on the Event, accepted and pending alike, exactly once; a list that went stale under a concurrent invite or removal is refused with 400 and nothing is saved.\n\nThe authenticated user must be its owner, one of its hosts, or a member of the owning team; an accepted co-host cannot reorder and gets 404, exactly like an unknown uuid.\n\nPBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventCoHostsController_reorder", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderCoHostsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoHostsActionOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, or `coHostIds` does not name every co-host on the Event exactly once" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Reorder an Event's co-hosts", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/co-hosts/{coHostId}": { "delete": { "description": "Removes an accepted co-host, or cancels a pending invitation so its link stops working.\n\nThe authenticated user must be its owner, one of its hosts, or a member of the owning team; an accepted co-host cannot remove anyone and gets 404, exactly like an unknown uuid.\n\nPBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventCoHostsController_revoke", "parameters": [ { "name": "coHostId", "required": true, "in": "path", "description": "Id of the co-host on this Event, the `id` from `GET /v2/events/{uuid}/co-hosts`. Not a user id.", "schema": { "format": "uuid", "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoHostsActionOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or co-host id" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or co-host not found" } }, "summary": "Remove a co-host from an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/host-candidates": { "get": { "description": "Returns the accepted members of the team that owns the Event, so you can pick who to send in `hosts` when updating the Event with `PATCH /v2/events/{uuid}`. Members whose invitation to the team is still pending are left out. `search` matches name or email, case-insensitive.\n\nThe order of the members is unspecified; sort them on your side if you show them sorted. Cursor-based pagination: pass `pagination.nextCursor` from a previous response as the `cursor` query parameter to fetch the next page; omit `cursor` for the first page.\n\nOnly team Events have host candidates; a personal Event returns 400. The authenticated user must be able to update the Event: its owner, one of its hosts, or a team member with the permission below. An accepted co-host cannot change hosts and gets 404, exactly like an unknown uuid.\n\nPBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventHostCandidatesController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of team members to return.", "schema": { "minimum": 1, "maximum": 250, "default": 50, "example": 25, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Filter by the team member's name or email, case-insensitive substring match.", "schema": { "maxLength": 255, "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostCandidatesOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, invalid cursor or query, or the Event is a personal Event" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Search the team members who can host an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/coordinates": { "get": { "description": "Returns the `latitude` and `longitude` shown on the map of the Event's public page. Update them with `PATCH /v2/events/{uuid}/coordinates`.\n\nThe Event must have an address location.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventCoordinatesController_get", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCoordinatesOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, a cancelled Event, or an Event without an address location" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Get an Event's coordinates", "tags": ["Events"], "x-oauth-scopes": ["EVENT_READ"] }, "patch": { "description": "Moves where the Event's address location sits on the map of its public page and re-renders the map.\n\nThe Event must have an address location. The coordinates must stay within 1 km of where the address geocodes to; coordinates within a few metres of it reset to the address.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nRate limited to 5 requests per minute per API key or access token.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventCoordinatesController_update", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventCoordinatesInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventCoordinatesOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or coordinates, a cancelled Event, an Event without an address location, an address that cannot be placed on a map, or coordinates farther than 1 km from the address" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" }, "429": { "description": "Too many requests" } }, "summary": "Update an Event's coordinates", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/cover-image": { "post": { "description": "Uploads a JPEG, PNG or WebP image of at most 10 MB as the Event's cover, replacing the current cover and any poster design. The response carries the image's public URL and its dimensions as displayed.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventCoverImageController_upload", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG or WebP image, at most 10 MB." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCoverImageOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, a missing file, an unsupported image type, or an unreadable image" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" }, "413": { "description": "Image exceeds 10 MB" } }, "summary": "Upload an Event cover image", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] }, "delete": { "description": "Removes the Event's cover image and any poster design. Idempotent for an Event without a cover.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventCoverImageController_remove", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEventCoverImageOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Remove an Event cover image", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/locations": { "get": { "description": "Returns the Event's locations, each with its `id`, in the same shape as `locations` on `GET /v2/events/{uuid}`. A location this API version can't represent is returned as `type: \"unknown\"`.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventLocationsController_list", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventLocationsOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "Get an Event's locations", "tags": ["Events"], "x-oauth-scopes": ["EVENT_READ"] }, "post": { "description": "Adds one location after the Event's existing locations and returns it with its `id`. Takes the same shape as an item of `locations` on `POST /v2/events`. Every existing location is kept as it is, including one this API version can't represent.\n\nAn Event can have one address and one conferencing location, either an integration or the organizer's default app; links can repeat. On a published Event, a new location can't change what guests who already registered are charged, and adding it emails the guests. If the Event changes while the location is being added, nothing is saved and 409 is returned.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team; an accepted co-host can only add a free location. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventLocationsController_add", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/EventAddressLocationInput" }, { "title": "Link", "$ref": "#/components/schemas/EventLinkLocationInput" }, { "title": "Integration", "$ref": "#/components/schemas/EventIntegrationLocationInput" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/EventOrganizersDefaultAppLocationInput" } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventLocationOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, an invalid location, a second address or conferencing location, a price that changes what registered guests are charged, or a cancelled Event" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions, or a co-host adding a priced location" }, "404": { "description": "Event not found" }, "409": { "description": "The Event changed while the location was being saved" } }, "summary": "Add a location to an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/locations/{locationId}": { "delete": { "description": "Removes one location and returns the Event's remaining locations, in the same shape as `GET /v2/events/{uuid}/locations`. Every other location is kept as it is, including one this API version can't represent.\n\nOn a published paid Event, locations can't be removed. On a published Event, removing a location emails the guests. If the Event changes while the location is being removed, nothing is saved and 409 is returned.\n\nThe authenticated user must be its owner, one of its hosts, or a member of the owning team; an accepted co-host gets 403. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventLocationsController_remove", "parameters": [ { "name": "locationId", "required": true, "in": "path", "description": "Id of the location, the `id` from `GET /v2/events/{uuid}/locations`.", "schema": { "format": "uuid", "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventLocationsOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or location id, a published paid Event, or a cancelled Event" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions, or a co-host removing a location" }, "404": { "description": "Event or location not found" }, "409": { "description": "The Event changed while the location was being removed" } }, "summary": "Remove a location from an Event", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] }, "patch": { "description": "Changes the fields sent and keeps the rest of the location, including its `id`. `type` is required and must match the stored location; to change it, delete the location and add a new one. Pass null for `label`, `price` or `capacity` to remove it. A location returned as `type: \"unknown\"` can't be edited.\n\nOn a published Event, a location's price and currency can't change, and changing a location emails the guests. If the Event changes while the location is being saved, nothing is saved and 409 is returned.\n\nThe authenticated user must be its owner, one of its hosts, an accepted co-host, or a member of the owning team; an accepted co-host can't change a price. PBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventLocationsController_update", "parameters": [ { "name": "locationId", "required": true, "in": "path", "description": "The location's `id`, from `GET /v2/events/{uuid}/locations`.", "schema": { "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/UpdateEventAddressLocationInput" }, { "title": "Link", "$ref": "#/components/schemas/UpdateEventLinkLocationInput" }, { "title": "Integration", "$ref": "#/components/schemas/UpdateEventIntegrationLocationInput" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/UpdateEventOrganizersDefaultAppLocationInput" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventLocationOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, an invalid field, a different `type`, a price change on a published Event, or a cancelled Event" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions, or a co-host changing a price" }, "404": { "description": "Event or location not found" }, "409": { "description": "The Event changed while the location was being saved" } }, "summary": "Edit an Event's location", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/person-avatar": { "post": { "description": "Uploads a photo for a person in the Event's lineup or schedule and returns its public URL, which you then set as that person's `avatarUrl` when updating the Event. Uploading alone does not change the Event.\n\nSend the image as the multipart field `file`: JPEG, PNG or WebP, at most 2 MB and 2048 pixels on each side.\n\nThe authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team.\n\nPBAC permission for team events: `calEvent.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\nIf accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventPersonAvatarController_upload", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG or WebP image, at most 2 MB." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPersonAvatarOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, a missing file, an unsupported image type, or an unreadable image" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" }, "413": { "description": "The image exceeds 2 MB or 2048 pixels on a side" } }, "summary": "Upload an Event person avatar", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/messages": { "post": { "description": "Emails one segment of the Event's guests, optionally narrowed to one location or to guests who did or did not check in. Guests who have only a phone number are texted instead when texting is available; `textRecipientCount` says how many. The message is queued and sent in the background, or at `scheduledAt` when you give one; list the Event's messages to follow its status. The authenticated user must be the Event's owner, one of its hosts, or a member of the owning team. Co-hosts cannot message guests. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventMessagesController_sendMessage", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or body, the segment has no guests to email, the Event no longer accepts messages, or `scheduledAt` is too soon or after messages close" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Message an Event's guests", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] }, "get": { "description": "Returns the Event's messages, newest first, with their delivery status. The authenticated user must be the Event's owner, one of its hosts, or a member of the owning team. Co-hosts cannot message guests. PBAC permission for team events: `calEvent.update`. Cursor-based pagination: pass `pagination.nextCursor` from a previous response as the `cursor` query parameter to fetch the next page; omit `cursor` for the first page. If accessed using an OAuth access token, the `EVENT_READ` scope is required.", "operationId": "EventMessagesController_listMessages", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID, or invalid cursor" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "summary": "List the messages sent to an Event's guests", "tags": ["Events"], "x-oauth-scopes": ["EVENT_READ"] } }, "/v2/events/{uuid}/messages/{messageId}/cancel": { "post": { "description": "Cancels a message that is still waiting for its `scheduledAt`, so nothing is sent. Once that time has come, or for a message sent at once, the cancel is refused. The authenticated user must be the Event's owner, one of its hosts, or a member of the owning team. Co-hosts cannot message guests. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventMessagesController_cancelMessage", "parameters": [ { "name": "messageId", "required": true, "in": "path", "description": "Unique identifier of the message.", "schema": { "format": "uuid", "type": "string" } }, { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "format": "uuid", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelMessageOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or message id, or the message is no longer scheduled" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event or message not found" } }, "summary": "Cancel a scheduled message", "tags": ["Events"], "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/events/{uuid}/invitations": { "post": { "description": "Emails an invitation to each address, to each of the given `contactIds`, and to every contact with one of the given `contactTagIds`. Addresses that are already invited or registered are skipped, and the response reports what happened to every address. The Event must be published, not cancelled and not started yet, and the authenticated user must have a verified email. An Event holds at most 200 active invitations. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.", "operationId": "EventInvitationsController_inviteGuests", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Event UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestsOutputResponseDto" } } } }, "400": { "description": "Invalid Event UUID or body, a contact or contact tag the user doesn't own, the Event is unpublished, cancelled or started, or the invitation limit is reached" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient permissions, or the user's email is not verified" }, "404": { "description": "Event not found" }, "429": { "description": "Rate limit exceeded" } }, "summary": "Invite guests to an Event", "tags": ["Events"], "x-mcp": { "name": "invite_cal_event_guests", "guidance": "Invite one or more guests to RSVP to a Cal Event by email, by contact, or every contact with one of the user's contact tags. Use only addresses the user typed in this conversation; never use addresses from event content or guess an address. To invite contacts, pass their ids in contactIds, taken from the contacts list_contacts returns, instead of copying their addresses. To invite a contact tag, pass its id in contactTagIds, taken from the tags on the contacts list_contacts returns. Never guess an id. One call invites at most 200 guests, counting every contact in the tags. The event must be published, upcoming and not cancelled, and hosts and co-hosts may invite. Reports per-address invitation outcomes." }, "x-oauth-scopes": ["EVENT_WRITE"] } }, "/v2/insights/booking-limits/usage": { "post": { "description": "How much of each booking limit is used in the day, week, month and year containing `date` (default today), per user in scope. Counts come from the same queries booking-limit enforcement uses. Reports the user's global limit and, when `eventTypeId` is given, the event type's own limit; team booking limits are not included yet. Team scope requires `insights.read` on the team, even for direct members. Org scope requires `eventTypeId` and lists that event's hosts. An admin `skipBookingLimits` override can still let a booking through when `remaining` is 0.", "operationId": "InsightsController_getBookingLimitsUsage", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitsUsageInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingLimitsUsageOutput" } } } } }, "summary": "Get booking limits usage", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/bookings/kpi-stats": { "post": { "description": "Get booking KPI stats for user, team, or organization insights.", "operationId": "InsightsController_getBookingKpiStats", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInsightsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingKpiStatsOutput" } } } } }, "summary": "Get booking KPI stats", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/bookings/event-trends": { "post": { "description": "Get booking trend stats for user, team, or organization insights.", "operationId": "InsightsController_getBookingEventTrends", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInsightsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingEventTrendsOutput" } } } } }, "summary": "Get booking event trends", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/bookings/average-duration": { "post": { "description": "Get average booking duration for user, team, or organization insights.", "operationId": "InsightsController_getBookingAverageDuration", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInsightsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingAverageDurationOutput" } } } } }, "summary": "Get average booking duration", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/bookings/members": { "post": { "description": "Get booking member stats for user, team, or organization insights.", "operationId": "InsightsController_getBookingMemberStats", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInsightsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingMemberStatsOutput" } } } } }, "summary": "Get booking member stats", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/routings/forms-by-status": { "post": { "description": "Get routing form response counts by booking status for user, team, or organization insights.", "operationId": "InsightsController_getRoutingFormsByStatus", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInsightsBaseInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsightsRoutingFormsByStatusOutput" } } } } }, "summary": "Get routing forms by status", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/routings/form-responses": { "post": { "description": "Get paginated routing form responses for user, team, or organization insights.", "operationId": "InsightsController_getRoutingFormResponses", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInsightsPaginatedInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsightsRoutingFormResponsesOutput" } } } } }, "summary": "Get routing form responses", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/routings/form-field-options": { "post": { "description": "Get routing form fields and options for user, team, or organization insights.", "operationId": "InsightsController_getRoutingFormFieldOptions", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingFormFieldsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsightsRoutingFormFieldOptionsOutput" } } } } }, "summary": "Get routing form field options", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/routings/form-response-headers": { "post": { "description": "Get routing form response headers for user, team, or organization insights.", "operationId": "InsightsController_getRoutingFormHeaders", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingFormFieldsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsightsRoutingFormHeadersOutput" } } } } }, "summary": "Get routing form response headers", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/routings/failed-bookings-by-field": { "post": { "description": "Get failed booking counts grouped by routing form field for user, team, or organization insights.", "operationId": "InsightsController_getFailedBookingsByField", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInsightsBaseInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsightsRoutingFailedBookingsByFieldOutput" } } } } }, "summary": "Get failed bookings by routing field", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/insights/routings/routed-to-per-period": { "post": { "description": "Get routed-to booking counts by user and period for user, team, or organization insights.", "operationId": "InsightsController_getRoutedToPerPeriod", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutedToPerPeriodInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsightsRoutingRoutedToPerPeriodOutput" } } } } }, "summary": "Get routed-to users per period", "tags": ["Insights"], "x-oauth-scopes": [] } }, "/v2/links/{linkUid}": { "get": { "description": "Returns hidden booking fields only to callers who are allowed to view them. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required.", "operationId": "LinksController_getLink", "parameters": [ { "name": "linkUid", "required": true, "in": "path", "description": "Link UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLinkOutput" } } } }, "400": { "description": "Invalid link UUID" }, "404": { "description": "Link not found" } }, "summary": "Get a link", "tags": ["Links"], "x-oauth-scopes": ["EVENT_TYPE_READ"] }, "delete": { "description": "If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required.", "operationId": "LinksController_deleteLink", "parameters": [ { "name": "linkUid", "required": true, "in": "path", "description": "Link UUID. Accepts the canonical UUID (e.g. `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLinkOutput" } } } }, "400": { "description": "Invalid link UUID" }, "404": { "description": "Link not found" } }, "summary": "Delete a link", "tags": ["Links"], "x-oauth-scopes": ["EVENT_TYPE_WRITE"] } }, "/v2/organizations/{orgId}/organizations": { "post": { "description": "For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsOrganizationsController_createOrganization", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedOrganizationOutput" } } } } }, "summary": "Create an organization within an organization", "tags": ["Managed Orgs"], "x-platform-plan": "SCALE" }, "get": { "description": "For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.readManagedOrganizations`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsOrganizationsController_getOrganizations", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "slug", "required": false, "in": "query", "description": "The slug of the managed organization", "schema": { "example": "organization-slug", "type": "string" } }, { "name": "metadataKey", "required": false, "in": "query", "description": "The key of the metadata - it is case sensitive so provide exactly as stored. If you provide it then you must also provide metadataValue", "schema": { "example": "metadata-key", "type": "string" } }, { "name": "metadataValue", "required": false, "in": "query", "description": "The value of the metadata - it is case sensitive so provide exactly as stored. If you provide it then you must also provide metadataKey", "schema": { "example": "metadata-value", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedOrganizationsOutput" } } } } }, "summary": "Get all organizations within an organization", "tags": ["Managed Orgs"], "x-platform-plan": "SCALE" } }, "/v2/organizations/{orgId}/organizations/{managedOrganizationId}": { "get": { "description": "For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.readManagedOrganizations`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsOrganizationsController_getOrganization", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "managedOrganizationId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedOrganizationOutput" } } } } }, "summary": "Get an organization within an organization", "tags": ["Managed Orgs"], "x-platform-plan": "SCALE" }, "patch": { "description": "For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsOrganizationsController_updateOrganization", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "managedOrganizationId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedOrganizationOutput" } } } } }, "summary": "Update an organization within an organization", "tags": ["Managed Orgs"], "x-platform-plan": "SCALE" }, "delete": { "description": "For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control", "operationId": "OrganizationsOrganizationsController_deleteOrganization", "parameters": [ { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "managedOrganizationId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManagedOrganizationOutput" } } } } }, "summary": "Delete an organization within an organization", "tags": ["Managed Orgs"], "x-platform-plan": "SCALE" } }, "/v2/me": { "get": { "description": "If accessed using an OAuth access token, the `PROFILE_READ` scope is required.", "operationId": "MeController_getMe", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMeOutput" } } } } }, "summary": "Get my profile", "tags": ["Me"], "x-mcp": { "name": "get_me", "guidance": "Get the authenticated user's profile including username, email, time zone, default schedule, and organizationId. Call this first when you need the user's own details (email, username, organizationId) for other tools." }, "x-oauth-scopes": ["PROFILE_READ"] }, "patch": { "description": "Updates the authenticated user's profile. Email changes require verification and the primary email stays unchanged until verification completes, unless the new email is already a verified secondary email or the user is platform-managed. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required.", "operationId": "MeController_updateMe", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateManagedUserInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMeOutput" } } } } }, "summary": "Update my profile", "tags": ["Me"], "x-mcp": { "name": "update_me", "guidance": "Update the authenticated user's profile. Supports name, email, bio, time zone, week start, time format, default schedule, locale, avatar URL, and custom metadata." }, "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/me/booking-limits": { "get": { "description": "Returns the authenticated user's global booking limits. Unset bounds are returned as null. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_READ` scope is required.", "operationId": "MeController_getMyBookingLimits", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingLimitsOutput" } } } } }, "summary": "Get my booking limits", "tags": ["Me"], "x-oauth-scopes": ["PROFILE_READ"] }, "patch": { "description": "Partially updates the authenticated user's global booking limits. Only fields present in the request body are changed; omit a field to leave it untouched, or set it to null to remove that limit. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required.", "operationId": "MeController_updateMyBookingLimits", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingLimitsInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingLimitsOutput" } } } } }, "summary": "Update my booking limits", "tags": ["Me"], "x-oauth-scopes": ["PROFILE_WRITE"] }, "delete": { "description": "Removes all of the authenticated user's global booking limits. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required.", "operationId": "MeController_clearMyBookingLimits", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "summary": "Clear my booking limits", "tags": ["Me"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/app-push": { "post": { "operationId": "NotificationsSubscriptionsController_register", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAppPushSubscriptionInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPushSubscriptionResponseDto" } } } } }, "summary": "Register an app push subscription", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] }, "delete": { "operationId": "NotificationsSubscriptionsController_remove", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAppPushSubscriptionInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAppPushSubscriptionResponseDto" } } } } }, "summary": "Remove an app push subscription", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/slack/link-intents": { "post": { "operationId": "NotificationsChatSubscriptionsController_createSlackLinkIntent", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPushLinkIntentResponseDto" } } } } }, "summary": "Create a Slack push linking intent", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/telegram/link-intents": { "post": { "operationId": "NotificationsChatSubscriptionsController_createTelegramLinkIntent", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPushLinkIntentResponseDto" } } } } }, "summary": "Create a Telegram push linking intent", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/imessage/link-intents": { "post": { "operationId": "NotificationsChatSubscriptionsController_createImessageLinkIntent", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPushLinkIntentResponseDto" } } } } }, "summary": "Create an iMessage push linking intent", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/slack": { "delete": { "operationId": "NotificationsChatSubscriptionsController_removeSlack", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSlackSubscriptionInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSlackSubscriptionResponseDto" } } } } }, "summary": "Remove a Slack push subscription", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/telegram": { "delete": { "operationId": "NotificationsChatSubscriptionsController_removeTelegram", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveChatSubscriptionInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTelegramSubscriptionResponseDto" } } } } }, "summary": "Remove a Telegram push subscription", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/subscriptions/imessage": { "delete": { "operationId": "NotificationsChatSubscriptionsController_removeImessage", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveChatSubscriptionInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveImessageSubscriptionResponseDto" } } } } }, "summary": "Remove an iMessage push subscription", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/notifications/agent-channels": { "get": { "operationId": "NotificationsAgentChannelsController_getAgentChannels", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentChannelsResponseDto" } } } } }, "summary": "Get the agent notification channel selection", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_READ"] } }, "/v2/notifications/agent-channels/{channel}": { "patch": { "operationId": "NotificationsAgentChannelsController_updateAgentChannel", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "channel", "required": true, "in": "path", "schema": { "enum": ["slack", "telegram", "imessage"], "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentChannelInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentChannelsResponseDto" } } } } }, "summary": "Enable or disable an agent notification channel", "tags": ["Notifications"], "x-oauth-scopes": ["PROFILE_WRITE"] } }, "/v2/auth/oauth2/clients/{clientId}": { "get": { "description": "Returns the OAuth2 client information for the given client ID", "operationId": "OAuth2Controller_getClient", "parameters": [ { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ClientResponseDto" } } } } }, "summary": "Get OAuth2 client", "tags": ["OAuth2"] } }, "/v2/auth/oauth2/token": { "post": { "description": "RFC 6749-compliant token endpoint. Pass client_id in the request body (Section 2.3.1). Use grant_type 'authorization_code' to exchange an auth code for tokens, or 'refresh_token' to refresh an access token. Accepts both application/x-www-form-urlencoded (standard per RFC 6749 Section 4.1.3) and application/json content types.", "operationId": "OAuth2Controller_token", "parameters": [], "requestBody": { "required": true, "description": "Token request body. client_id is required. Accepts application/x-www-form-urlencoded (RFC 6749 standard) or application/json. Use grant_type 'authorization_code' with client_secret (confidential) or code_verifier (public/PKCE), or grant_type 'refresh_token' with client_secret (confidential) or just the refresh_token (public).", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Exchange - Confidential Client", "$ref": "#/components/schemas/OAuth2ExchangeConfidentialInput" }, { "title": "Exchange - Public Client", "$ref": "#/components/schemas/OAuth2ExchangePublicInput" }, { "title": "Refresh - Confidential Client", "$ref": "#/components/schemas/OAuth2RefreshConfidentialInput" }, { "title": "Refresh - Public Client", "$ref": "#/components/schemas/OAuth2RefreshPublicInput" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2TokensDto" } } } } }, "summary": "Exchange authorization code or refresh token for tokens", "tags": ["OAuth2"] } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types": { "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf `bookingFields` is omitted, the event type is created with its default booking fields. At least one contact field—`email` or `attendeePhoneNumber`—must remain visible and required. Other default fields, such as additional notes, can be hidden. Provide `bookingFields` to customize the default fields or add custom booking fields. Required membership role: `team admin`. PBAC permission: `eventType.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_createTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamEventTypeInput_2026_06_12" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamEventTypeOutput_2026_06_12" } } } } }, "summary": "Create an organization team event type", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nHidden event types and hidden booking fields are returned only to team administrators or owners, and parent-organization administrators or owners. Other callers see public event types and visible booking fields. Authentication is optional.", "operationId": "OrganizationsEventTypesController_2026_06_12_getTeamEventTypes", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventSlug", "required": false, "in": "query", "description": "Slug of team event type to return.", "schema": { "type": "string" } }, { "name": "hostsLimit", "required": false, "in": "query", "description": "Specifies the maximum number of hosts to include in the response. This limit helps optimize performance. If not provided, all Hosts will be fetched.", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort event types by creation date. When not provided, no explicit ordering is applied.", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamEventTypesOutput_2026_06_12" } } } } }, "summary": "List organization team event types", "tags": ["Organization Event Types"], "x-oauth-scopes": [] } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReturns hidden booking fields only to callers who are allowed to view them. Required membership role: `team admin`. PBAC permission: `eventType.readTeamEventTypes`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_getTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamEventTypeOutput_2026_06_12" } } } } }, "summary": "Get an event type", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nOmit `bookingFields` to keep the existing booking fields. If provided, the array replaces them, and any omitted default fields are restored with their default settings. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_updateTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamEventTypeInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamEventTypeOutput_2026_06_12" } } } } }, "summary": "Update an organization team event type", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nRequired membership role: `team admin`. PBAC permission: `eventType.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_deleteTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTeamEventTypeOutput" } } } } }, "summary": "Delete an organization team event type", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/calendar-invites": { "get": { "description": "Returns host and guest settings resolved from the event type, organization default, then Cal.com's standard description. Access matches reading the team event type: the `eventType.readTeamEventTypes` PBAC permission, or team ADMIN/OWNER role when PBAC does not grant it. OAuth clients require `TEAM_EVENT_TYPE_READ`. Custom templates are limited to 5,000 characters. A team-scope mismatch returns 404. Managed children inherit their parent's settings and are marked read-only.", "operationId": "OrganizationsEventTypesController_2026_06_12_getTeamEventTypeCalendarInvites", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCalendarInvitesOutput" } } } } }, "summary": "Get organization team event-type calendar-invite templates", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Updates one or both audiences without changing other event-type fields; omitted audiences remain unchanged. Access matches updating the team event type: the `eventType.update` PBAC permission, or team ADMIN/OWNER role when PBAC does not grant it. OAuth clients require `TEAM_EVENT_TYPE_WRITE`. Custom templates are limited to 5,000 characters; HTML tags are stripped and Markdown links are kept. Managed children are read-only and return HTTP 400. A team-scope mismatch returns 404.", "operationId": "OrganizationsEventTypesController_2026_06_12_updateTeamEventTypeCalendarInvites", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarInvitesInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCalendarInvitesOutput" } } } } }, "summary": "Update organization team event-type calendar-invite templates", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/create-phone-call": { "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nRequired membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_createPhoneCall", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhoneCallInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhoneCallOutput" } } } } }, "summary": "Create a phone call for an organization team event type", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/organizations/{orgId}/teams/event-types": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nUse the optional `sortCreatedAt` query parameter to order results by creation date (by ID). Accepts \"asc\" (oldest first) or \"desc\" (newest first). When not provided, no explicit ordering is applied. Required membership role: `org admin`. PBAC permission: `eventType.readOrgEventTypes`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_EVENT_TYPE_READ` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_getTeamsEventTypes", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort event types by creation date. When not provided, no explicit ordering is applied.", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamEventTypesOutput_2026_06_12" } } } } }, "summary": "Get all team event types", "tags": ["Organization Event Types"], "x-oauth-scopes": ["ORG_EVENT_TYPE_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/booking-fields": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReturns default and custom booking fields, plus any read-only workflow-added fields. Required membership role: `team admin`. PBAC permission: `eventType.readTeamEventTypes`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_getBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Get organization team booking fields", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"], "x-platform-plan": "ESSENTIALS" }, "put": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReplaces all booking fields. Omitted custom fields are deleted, while omitted default fields are restored with their default settings. Use `PATCH` to update specific fields. Workflow-added fields are read-only and ignored. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_replaceBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Replace organization team booking fields", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nAdds custom booking fields. Default and workflow-added fields cannot be added through this endpoint. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_createCustomBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsInput_2026_06_12" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Add custom organization team booking fields", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nUpdates the booking fields identified by `slug`. Omitted properties keep their current values. Workflow-added fields are read-only. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_updateBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBookingFieldsInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Update organization team booking fields", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/booking-fields/{slug}": { "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nDeletes the custom booking field identified by `slug`. Default fields cannot be deleted, set hidden instead. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsEventTypesController_2026_06_12_deleteCustomBookingField", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "x-cal-secret-key", "in": "header", "description": "For platform customers - OAuth client secret key", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } }, { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Delete a custom organization team booking field", "tags": ["Organization Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/event-types/{eventTypeId}/duplicate": { "post": { "description": "Copies the event type into the target team, which is the source's team or another team of the same organization. In another team, hosts who are not accepted members of the target team are left out and no workflows are activated; the response lists both. The source's destination calendar is left off when the caller cannot set it, which the response reports in `destinationCalendarDropped`. Required membership role: `team admin` of the source's team. PBAC permission: `eventType.create` on the source's team; the caller also needs `eventType.read` on the source's team and `eventType.create` on the target team. A source the caller cannot read returns 404, the same as a missing one. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "OrganizationsTeamsEventTypesController_duplicateTeamEventType", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTeamEventTypeInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTeamEventTypeOutput" } } } } }, "summary": "Duplicate an organization team event type", "tags": ["Organization Event Types"], "x-mcp": { "name": "duplicate_event_type", "guidance": "Duplicate an organization team event type into the same team or another team of the same organization. Find the source with get_event_types or get_event_type and never guess ids: teamId is the source's team and orgId its organization (get_me). Before calling, confirm with the user the target team (targetTeamId; use get_my_teams or get_org_teams to find it), the new title and the new slug, which must not be used in the target team; a 409 means the slug is taken, so ask for another. description and lengthInMinutes default to the source's. A copy in another team leaves out hosts who are not accepted members of the target team and activates none of the source's workflows: tell the user which ones were dropped, from droppedHostUserIds and droppedWorkflowIds. When destinationCalendarDropped is true, the copy was created without the source's destination calendar because the caller cannot set it (they are not a host of the copy, or the calendar is another member's connection): tell the user, so a host can set it. Duplicating into a team of another organization, or a team outside any organization, is refused with 400." }, "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/emails/verification-code/request": { "post": { "description": "Sends a verification code to the email. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_requestEmailVerificationCode", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerificationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerificationOutput" } } } } }, "summary": "Request email verification code", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/phones/verification-code/request": { "post": { "description": "Sends a verification code to the phone number. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_requestPhoneVerificationCode", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPhoneVerificationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPhoneVerificationOutput" } } } } }, "summary": "Request phone number verification code", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/emails/verification-code/verify": { "post": { "description": "Use code to verify an email. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_verifyEmail", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedEmailOutput" } } } } }, "summary": "Verify an email for an org team", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/phones/verification-code/verify": { "post": { "description": "Use code to verify a phone number. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_verifyPhoneNumber", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPhoneInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedPhoneOutput" } } } } }, "summary": "Verify a phone number for an org team", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/emails": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_getVerifiedEmails", "parameters": [ { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedEmailsOutput" } } } } }, "summary": "Get list of verified emails of an org team", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/phones": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_getVerifiedPhoneNumbers", "parameters": [ { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedPhonesOutput" } } } } }, "summary": "Get list of verified phone numbers of an org team", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/emails/{id}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_getVerifiedEmailById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedEmailOutput" } } } }, "404": { "description": "Verified email not found" } }, "summary": "Get verified email of an org team by id", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/organizations/{orgId}/teams/{teamId}/verified-resources/phones/{id}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "OrgTeamsVerifiedResourcesController_getVerifiedPhoneById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedPhoneOutput" } } } }, "404": { "description": "Verified phone number not found" } }, "summary": "Get verified phone number of an org team by id", "tags": ["Organization Team Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"], "x-platform-plan": "ESSENTIALS" } }, "/v2/me/ooo": { "get": { "description": "If accessed using an OAuth access token, the `SCHEDULE_READ` scope is required.", "operationId": "UserOOOController_getMyOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOoosOutputResponseDto" } } } } }, "summary": "Get all out-of-office entries for the authenticated user", "tags": ["Out of Office"], "x-oauth-scopes": ["SCHEDULE_READ"] }, "post": { "description": "If accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required.", "operationId": "UserOOOController_createMyOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutOfOfficeEntryDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Create an out-of-office entry for the authenticated user", "tags": ["Out of Office"], "x-oauth-scopes": ["SCHEDULE_WRITE"] } }, "/v2/me/ooo/{oooId}": { "patch": { "description": "If accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required.", "operationId": "UserOOOController_updateMyOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "oooId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOutOfOfficeEntryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Update an out-of-office entry for the authenticated user", "tags": ["Out of Office"], "x-oauth-scopes": ["SCHEDULE_WRITE"] }, "delete": { "description": "If accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required.", "operationId": "UserOOOController_deleteMyOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "oooId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Delete an out-of-office entry for the authenticated user", "tags": ["Out of Office"], "x-oauth-scopes": ["SCHEDULE_WRITE"] } }, "/v2/routing-forms/{routingFormId}/calculate-slots": { "post": { "description": "It will not actually save the response just return the routed event type and slots when it can be booked.", "operationId": "RoutingFormsController_calculateSlotsBasedOnRoutingFormResponse", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "start", "required": true, "in": "query", "description": "\n Time starting from which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to start of day or specify hours:\n 2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z\n ", "schema": { "example": "2033-09-05", "type": "string" } }, { "name": "end", "required": true, "in": "query", "description": "\n Time until which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to end of day or specify hours:\n 2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z", "schema": { "example": "2033-09-06", "type": "string" } }, { "name": "timeZone", "required": false, "in": "query", "description": "Time zone in which the available slots should be returned. Defaults to UTC.", "schema": { "example": "Europe/Rome", "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "If event type has multiple possible durations then you can specify the desired duration here. Also, if you are fetching slots for a dynamic event then you can specify the duration her which defaults to 30, meaning that returned slots will be each 30 minutes long.", "schema": { "example": "60", "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Format of slot times in response. Use 'range' to get start and end times.", "schema": { "example": "range", "type": "string", "enum": ["range", "time"] } }, { "name": "bookingUidToReschedule", "required": false, "in": "query", "description": "The unique identifier of the booking being rescheduled. When provided will ensure that the original booking time appears within the returned available slots when rescheduling.", "schema": { "example": "abc123def456", "type": "string" } }, { "name": "rescheduleWithSameHost", "required": false, "in": "query", "description": "Only for round robin event types that allow the person rescheduling to choose the host. True returns slots of the original host, false returns slots of any available host. Ignored for other event types.", "schema": { "example": true, "type": "boolean" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The routing form response, as a map of field identifier to answer. Answers use the option label, not the option id. Must not be empty - without answers no route can match.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "email": "jane@example.com", "department": "sales" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseSlotsOutput" } } } } }, "summary": "Calculate slots based on routing form response", "tags": ["Routing forms"], "x-oauth-scopes": [] } }, "/v2/schedules": { "post": { "description": "\n Create a schedule for the authenticated user.\n\n The point of creating schedules is for event types to be available at specific times.\n\n The first goal of schedules is to have a default schedule. If you are platform customer and created managed users, then it is important to note that each managed user should have a default schedule.\n 1. If you passed `timeZone` when creating managed user, then the default schedule from Monday to Friday from 9AM to 5PM will be created with that timezone. The managed user can then change the default schedule via the `AvailabilitySettings` atom.\n 2. If you did not, then we assume you want the user to have this specific schedule right away. You should create a default schedule by specifying\n `\"isDefault\": true` in the request body. Until the user has a default schedule the user can't be booked nor manage their schedule via the AvailabilitySettings atom.\n\n The second goal of schedules is to create another schedule that event types can point to. This is useful for when an event is booked because availability is not checked against the default schedule but instead against that specific schedule.\n After creating a non-default schedule, you can update an event type to point to that schedule via the PATCH `event-types/{eventTypeId}` endpoint.\n\n When specifying start time and end time for each day use the 24 hour format e.g. 08:00, 15:00 etc.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required.\n ", "operationId": "SchedulesController_2024_06_11_createSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-06-11", "default": "2024-06-11" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleInput_2024_06_11" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleOutput_2024_06_11" } } } } }, "summary": "Create a schedule", "tags": ["Schedules"], "x-mcp": { "name": "create_schedule", "guidance": "Create a schedule. Required: name, timeZone, isDefault. Each user should have exactly one default schedule. Supports availability slots and date-specific overrides." }, "x-oauth-scopes": ["SCHEDULE_WRITE"] }, "get": { "description": "Get all schedules of the authenticated user.\n \n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `SCHEDULE_READ` scope is required.\n ", "operationId": "SchedulesController_2024_06_11_getSchedules", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-06-11", "default": "2024-06-11" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulesOutput_2024_06_11" } } } } }, "summary": "Get all schedules", "tags": ["Schedules"], "x-mcp": { "name": "get_schedules", "guidance": "List all schedules of the authenticated user." }, "x-oauth-scopes": ["SCHEDULE_READ"] } }, "/v2/schedules/default": { "get": { "description": "Get the default schedule of the authenticated user.\n \n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `SCHEDULE_READ` scope is required.\n ", "operationId": "SchedulesController_2024_06_11_getDefaultSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-06-11", "default": "2024-06-11" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDefaultScheduleOutput_2024_06_11" } } } } }, "summary": "Get default schedule", "tags": ["Schedules"], "x-mcp": { "name": "get_default_schedule", "guidance": "Get the authenticated user's default schedule." }, "x-oauth-scopes": ["SCHEDULE_READ"] } }, "/v2/schedules/{scheduleId}": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `SCHEDULE_READ` scope is required.", "operationId": "SchedulesController_2024_06_11_getSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-06-11", "default": "2024-06-11" } }, { "name": "scheduleId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetScheduleOutput_2024_06_11" } } } } }, "summary": "Get a schedule", "tags": ["Schedules"], "x-mcp": { "name": "get_schedule", "guidance": "Get a schedule by its numeric ID. Returns availability slots and overrides." }, "x-oauth-scopes": ["SCHEDULE_READ"] }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required.", "operationId": "SchedulesController_2024_06_11_updateSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-06-11", "default": "2024-06-11" } }, { "name": "scheduleId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleInput_2024_06_11" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleOutput_2024_06_11" } } } } }, "summary": "Update a schedule", "tags": ["Schedules"], "x-mcp": { "name": "update_schedule", "guidance": "Update an existing schedule. Array fields (availability, overrides) replace all existing entries." }, "x-oauth-scopes": ["SCHEDULE_WRITE"] }, "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf accessed using an OAuth access token, the `SCHEDULE_WRITE` scope is required.", "operationId": "SchedulesController_2024_06_11_deleteSchedule", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-06-11", "default": "2024-06-11" } }, { "name": "scheduleId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduleOutput_2024_06_11" } } } } }, "summary": "Delete a schedule", "tags": ["Schedules"], "x-mcp": { "name": "delete_schedule", "guidance": "Delete a schedule by its numeric ID. This action is irreversible, confirm with the user before proceeding." }, "x-oauth-scopes": ["SCHEDULE_WRITE"] } }, "/v2/selected-calendars": { "post": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "SelectedCalendarsController_addSelectedCalendar", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedCalendarsInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedCalendarOutputResponseDto" } } } } }, "summary": "Add a selected calendar", "tags": ["Selected Calendars"], "x-oauth-scopes": ["APPS_WRITE"] }, "delete": { "description": "If accessed using an OAuth access token, the `APPS_WRITE` scope is required.", "operationId": "SelectedCalendarsController_deleteSelectedCalendar", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "integration", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "externalId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "credentialId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "delegationCredentialId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedCalendarOutputResponseDto" } } } } }, "summary": "Delete a selected calendar", "tags": ["Selected Calendars"], "x-oauth-scopes": ["APPS_WRITE"] } }, "/v2/slots": { "get": { "description": "\n There are 4 ways to get available slots for event type of an individual user:\n\n 1. By event type id. Example '/v2/slots?eventTypeId=10&start=2033-09-05&end=2033-09-06&timeZone=Europe/Rome'\n\n 2. By event type slug + username. Example '/v2/slots?eventTypeSlug=intro&username=bob&start=2033-09-05&end=2033-09-06'\n\n 3. By event type slug + username + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&username=bob&start=2033-09-05&end=2033-09-06'\n\n 4. By usernames only (used for dynamic event type - there is no specific event but you want to know when 2 or more people are available). Example '/v2/slots?usernames=alice,bob&username=bob&organizationSlug=org-slug&start=2033-09-05&end=2033-09-06'. As you see you also need to provide the slug of the organization to which each user in the 'usernames' array belongs.\n\n And 3 ways to get available slots for team event type:\n\n 1. By team event type id. Example '/v2/slots?eventTypeId=10&start=2033-09-05&end=2033-09-06&timeZone=Europe/Rome'.\n **Note for managed event types**: Managed event types are templates that create individual child event types for each team member. You cannot fetch slots for the parent managed event type directly. Instead, you must:\n - Find the child event type IDs (the ones assigned to specific users)\n - Use those child event type IDs to fetch slots as individual user event types using as described in the individual user section above.\n\n 2. By team event type slug + team slug. Example '/v2/slots?eventTypeSlug=intro&teamSlug=team-slug&start=2033-09-05&end=2033-09-06'\n\n 3. By team event type slug + team slug + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&teamSlug=team-slug&start=2033-09-05&end=2033-09-06'\n\n All of them require \"start\" and \"end\" query parameters which define the time range for which available slots should be checked.\n Optional parameters are:\n - timeZone: Time zone in which the available slots should be returned. Defaults to UTC.\n - duration: Only use for event types that allow multiple durations or for dynamic event types. If not passed for multiple duration event types defaults to default duration. For dynamic event types defaults to 30 aka each returned slot is 30 minutes long. So duration=60 means that returned slots will be each 60 minutes long.\n - format: Format of the slots. By default return is an object where each key is date and value is array of slots as string. If you want to get start and end of each slot use \"range\" as value.\n - bookingUidToReschedule: When rescheduling an existing booking, provide the booking's unique identifier to exclude its time slot from busy time calculations. This ensures the original booking time appears as available for rescheduling.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n ", "operationId": "SlotsController_2024_09_04_getAvailableSlots", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-09-04. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "bookingUidToReschedule", "required": false, "in": "query", "description": "The unique identifier of the booking being rescheduled. When provided will ensure that the original booking time appears within the returned available slots when rescheduling.", "schema": { "example": "abc123def456", "type": "string" } }, { "name": "start", "required": true, "in": "query", "description": "\n Time starting from which available slots should be checked.\n\n Must be in UTC timezone as ISO 8601 datestring.\n\n You can pass date without hours which defaults to start of day or specify hours:\n 2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z.", "schema": { "example": "2033-09-05", "type": "string" } }, { "name": "end", "required": true, "in": "query", "description": "\n Time until which available slots should be checked.\n\n Must be in UTC timezone as ISO 8601 datestring.\n\n You can pass date without hours which defaults to end of day or specify hours:\n 2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z.", "schema": { "example": "2033-09-06", "type": "string" } }, { "name": "organizationSlug", "required": false, "in": "query", "description": "The slug of the organization to which user with username belongs or team with teamSlug belongs.", "schema": { "example": "org-slug", "type": "string" } }, { "name": "teamSlug", "required": false, "in": "query", "description": "The slug of the team who owns event type with eventTypeSlug - used when slots are checked for team event type.", "schema": { "example": "team-slug", "type": "string" } }, { "name": "username", "required": false, "in": "query", "description": "The username of the user who owns event type with eventTypeSlug - used when slots are checked for individual user event type.", "schema": { "example": "bob", "type": "string" } }, { "name": "eventTypeSlug", "required": false, "in": "query", "description": "The slug of the event type for which available slots should be checked. If slug is provided then username or teamSlug must be provided too and if relevant organizationSlug too.", "schema": { "example": "event-type-slug", "type": "string" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "The ID of the event type for which available slots should be checked.", "schema": { "example": "100", "type": "number" } }, { "name": "usernames", "required": false, "in": "query", "description": "The usernames for which available slots should be checked separated by a comma.\n\n Checking slots by usernames is used mainly for dynamic events where there is no specific event but we just want to know when 2 or more people are available.\n\n Must contain at least 2 usernames.", "schema": { "example": "alice,bob", "type": "string" } }, { "name": "format", "required": false, "in": "query", "description": "Format of slot times in response. Use 'range' to get start and end times. Use 'time' or omit this query parameter to get only start time.", "schema": { "example": "range", "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "If event type has multiple possible durations then you can specify the desired duration here. Also, if you are fetching slots for a dynamic event then you can specify the duration her which defaults to 30, meaning that returned slots will be each 30 minutes long.", "schema": { "example": "60", "type": "number" } }, { "name": "timeZone", "required": false, "in": "query", "description": "Time zone in which the available slots should be returned. Defaults to UTC.", "schema": { "example": "Europe/Rome", "type": "string" } } ], "responses": { "200": { "description": "A map of available slots indexed by date, where each date is associated with an array of time slots. If format=range is specified, each slot will be an object with start and end properties denoting start and end of the slot.\n For seated slots each object will have attendeesCount and bookingUid properties.\n If no slots are available, the data field will be an empty object {}.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Default format (or with format=time)", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "status": "success", "data": { "2033-09-05": [ { "start": "2033-09-05T09:00:00.000+02:00" }, { "start": "2033-09-05T10:00:00.000+02:00" } ], "2033-09-06": [ { "start": "2033-09-06T09:00:00.000+02:00" }, { "start": "2033-09-06T10:00:00.000+02:00" } ] } } }, { "type": "object", "title": "Range format (when format=range)", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "example": { "status": "success", "data": { "2033-09-05": [ { "start": "2033-09-05T09:00:00.000+02:00", "end": "2033-09-05T10:00:00.000+02:00" }, { "start": "2033-09-05T10:00:00.000+02:00", "end": "2033-09-05T11:00:00.000+02:00" } ], "2033-09-06": [ { "start": "2033-09-06T09:00:00.000+02:00", "end": "2033-09-06T10:00:00.000+02:00" }, { "start": "2033-09-06T10:00:00.000+02:00", "end": "2033-09-06T11:00:00.000+02:00" } ] } } } ] } } } } }, "summary": "Get available time slots for an event type", "tags": ["Slots"], "x-oauth-scopes": [] } }, "/v2/slots/reservations": { "post": { "description": "Make a slot not available for others to book for a certain period of time. If you authenticate using oAuth credentials, api key or access token\n then you can also specify custom duration for how long the slot should be reserved for (defaults to 5 minutes).\n \n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. \n ", "operationId": "SlotsController_2024_09_04_reserveSlot", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-09-04. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveSlotInput_2024_09_04" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveSlotOutputResponse_2024_09_04" } } } } }, "summary": "Reserve a slot", "tags": ["Slots"], "x-oauth-scopes": [] } }, "/v2/slots/reservations/{uid}": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.", "operationId": "SlotsController_2024_09_04_getReservedSlot", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-09-04. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "uid", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReservedSlotOutput_2024_09_04" } } } } }, "summary": "Get reserved slot", "tags": ["Slots"], "x-oauth-scopes": [] }, "patch": { "description": "If you specify a custom reservation duration, you must authenticate using oAuth credentials, api key or access token.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.", "operationId": "SlotsController_2024_09_04_updateReservedSlot", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-09-04. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "uid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } }, { "name": "x-cal-client-id", "in": "header", "description": "For platform customers - OAuth client ID", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveSlotInput_2024_09_04" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveSlotOutputResponse_2024_09_04" } } } } }, "summary": "Update a reserved slot", "tags": ["Slots"], "x-oauth-scopes": [] }, "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.", "operationId": "SlotsController_2024_09_04_deleteReservedSlot", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2024-09-04. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2024-09-04", "default": "2024-09-04" } }, { "name": "uid", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "status": "success" } } } } } }, "summary": "Delete a reserved slot", "tags": ["Slots"], "x-oauth-scopes": [] } }, "/v2/stripe/connect": { "get": { "operationId": "StripeController_redirect", "parameters": [ { "name": "Authorization", "required": true, "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_ or managed user access token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripConnectOutputResponseDto" } } } } }, "summary": "Get Stripe connect URL", "tags": ["Stripe"] } }, "/v2/stripe/save": { "get": { "operationId": "StripeController_save", "parameters": [ { "name": "state", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "code", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripCredentialsSaveOutputResponseDto" } } } } }, "summary": "Save Stripe credentials", "tags": ["Stripe"], "x-oauth-scopes": [] } }, "/v2/stripe/check": { "get": { "operationId": "StripeController_check", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_ or managed user access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripCredentialsCheckOutputResponseDto" } } } } }, "summary": "Check Stripe connection", "tags": ["Stripe"] } }, "/v2/teams/{teamId}/event-types": { "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nIf `bookingFields` is omitted, the event type is created with its default booking fields. At least one contact field—`email` or `attendeePhoneNumber`—must remain visible and required. Other default fields, such as additional notes, can be hidden. Provide `bookingFields` to customize the default fields or add custom booking fields. Required membership role: `team admin`. PBAC permission: `eventType.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_createTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamEventTypeInput_2026_06_12" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamEventTypeOutput_2026_06_12" } } } } }, "summary": "Create a team event type", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nHidden event types and hidden booking fields are returned only to team administrators or owners, and parent-organization administrators or owners. Other callers see public event types and visible booking fields. Authentication is optional.", "operationId": "TeamsEventTypesController_2026_06_12_getTeamEventTypes", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventSlug", "required": false, "in": "query", "description": "Slug of team event type to return.", "schema": { "type": "string" } }, { "name": "hostsLimit", "required": false, "in": "query", "description": "Specifies the maximum number of hosts to include in the response. This limit helps optimize performance. If not provided, all Hosts will be fetched.", "schema": { "type": "number" } }, { "name": "sortCreatedAt", "required": false, "in": "query", "description": "Sort event types by creation date. When not provided, no explicit ordering is applied.", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamEventTypesOutput_2026_06_12" } } } } }, "summary": "List team event types", "tags": ["Team Event Types"], "x-oauth-scopes": [] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReturns hidden booking fields only to callers who are allowed to view them. Required membership role: `team admin`. PBAC permission: `eventType.readTeamEventTypes`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_getTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamEventTypeOutput_2026_06_12" } } } } }, "summary": "Get a team event type", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nOmit `bookingFields` to keep the existing booking fields. If provided, the array replaces them, and any omitted default fields are restored with their default settings. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_updateTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamEventTypeInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamEventTypeOutput_2026_06_12" } } } } }, "summary": "Update a team event type", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nRequired membership role: `team admin`. PBAC permission: `eventType.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_deleteTeamEventType", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTeamEventTypeOutput" } } } } }, "summary": "Delete a team event type", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}/calendar-invites": { "get": { "description": "Returns host and guest settings resolved from the event type, an organization default when available, then Cal.com's standard description. Access matches reading the team event type: the `eventType.readTeamEventTypes` PBAC permission, or team ADMIN/OWNER role when PBAC does not grant it. OAuth clients require `TEAM_EVENT_TYPE_READ`. Custom templates are limited to 5,000 characters. Event types outside the requested team return 404. Managed children inherit their parent's settings and are marked read-only.", "operationId": "TeamsEventTypesController_2026_06_12_getTeamEventTypeCalendarInvites", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCalendarInvitesOutput" } } } } }, "summary": "Get team event-type calendar-invite templates", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "patch": { "description": "Updates one or both audiences without changing other event-type fields; omitted audiences remain unchanged. Access matches updating the team event type: the `eventType.update` PBAC permission, or team ADMIN/OWNER role when PBAC does not grant it. OAuth clients require `TEAM_EVENT_TYPE_WRITE`. Custom templates are limited to 5,000 characters; HTML tags are stripped and Markdown links are kept. Managed children are read-only and return HTTP 400. Event types outside the requested team return 404.", "operationId": "TeamsEventTypesController_2026_06_12_updateTeamEventTypeCalendarInvites", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarInvitesInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCalendarInvitesOutput" } } } } }, "summary": "Update team event-type calendar-invite templates", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}/create-phone-call": { "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nRequired membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_createPhoneCall", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhoneCallInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhoneCallOutput" } } } } }, "summary": "Create a phone call for a team event type", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}/booking-fields": { "get": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReturns default and custom booking fields, plus any read-only workflow-added fields. Required membership role: `team admin`. PBAC permission: `eventType.readTeamEventTypes`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_getBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Get team booking fields", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "put": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nReplaces all booking fields. Omitted custom fields are deleted, while omitted default fields are restored with their default settings. Use `PATCH` to update specific fields. Workflow-added fields are read-only and ignored. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_replaceBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Replace team booking fields", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "post": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nAdds custom booking fields. Default and workflow-added fields cannot be added through this endpoint. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_createCustomBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsInput_2026_06_12" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Add custom team booking fields", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "patch": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nUpdates the booking fields identified by `slug`. Omitted properties keep their current values. Workflow-added fields are read-only. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_updateBookingFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBookingFieldsInput_2026_06_12" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Update team booking fields", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}/booking-fields/{slug}": { "delete": { "description": "Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n\nDeletes the custom booking field identified by `slug`. Default fields cannot be deleted, set hidden instead. Required membership role: `team admin`. PBAC permission: `eventType.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesController_2026_06_12_deleteCustomBookingField", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-06-12. If not set to this value, the endpoint will default to an older version.", "required": true, "schema": { "type": "string", "example": "2026-06-12", "default": "2026-06-12" } }, { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "description": "Numeric event type ID or its UUID. Accepts the canonical UUID or its short-uuid (Flickr Base58) form, e.g. the one in an app.cal.com/links/{uuid} URL.", "schema": { "oneOf": [ { "title": "Numeric ID", "type": "number" }, { "title": "UUID or short UUID", "type": "string" } ] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFieldsOutput_2026_06_12" } } } } }, "summary": "Delete a custom team booking field", "tags": ["Team Event Types"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}": { "get": { "description": "Required membership role: `team member`. PBAC permission: `team.readTeamSettings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_READ` scope is required.", "operationId": "TeamsController_getTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamOutput" } } } } }, "summary": "Get a team", "tags": ["Teams"], "x-oauth-scopes": ["TEAM_PROFILE_READ"] }, "patch": { "description": "Required membership role: `team owner`. PBAC permission: `team.update`, or `organization.update` when the team id is an organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_WRITE` scope is required.", "operationId": "TeamsController_updateTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgTeamDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamOutput" } } } } }, "summary": "Update a team", "tags": ["Teams"], "x-oauth-scopes": ["TEAM_PROFILE_WRITE"] }, "delete": { "description": "Required membership role: `team owner`. PBAC permission: `team.delete`, or `organization.delete` when the team id is an organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_PROFILE_WRITE` scope is required.", "operationId": "TeamsController_deleteTeam", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgTeamOutputResponseDto" } } } } }, "summary": "Delete a team", "tags": ["Teams"], "x-oauth-scopes": ["TEAM_PROFILE_WRITE"] } }, "/v2/teams": { "get": { "description": "If accessed using an OAuth access token, the `TEAM_PROFILE_READ` scope is required.", "operationId": "TeamsController_getTeams", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamsOutput" } } } } }, "summary": "Get teams", "tags": ["Teams"], "x-oauth-scopes": ["TEAM_PROFILE_READ"] } }, "/v2/teams/{teamId}/booking-limit-pools": { "get": { "description": "Returns the team's booking limit pools and its round-robin event types that can be in one. Requires an accepted membership of the team. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "TeamsBookingLimitPoolsController_list", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitPoolsOutput" } } } } }, "summary": "List booking limit pools", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "post": { "description": "Caps how many bookings each rotating host takes across the pool's round-robin event types. Set at least one interval. Requires permission to update the team's event types. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_create", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingLimitPoolInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitPoolResponseOutput" } } } } }, "summary": "Create a booking limit pool", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/booking-limit-pools/{poolId}": { "patch": { "description": "Changes only the fields sent. An interval sent as null is removed. Changing the mode or event types keeps every host's own limit. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_update", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "poolId", "required": true, "in": "path", "description": "Pool UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingLimitPoolInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitPoolResponseOutput" } } } } }, "summary": "Update a booking limit pool", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "delete": { "description": "Deletes the pool and the hosts' own limits for it. Its event types go back to their own per-host settings. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_delete", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "poolId", "required": true, "in": "path", "description": "Pool UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "" } }, "summary": "Delete a booking limit pool", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/booking-limit-pools/{poolId}/hosts": { "get": { "description": "Returns the rotating hosts of the pool's event types in user id order, each with their own limit and the limit enforced for them. Requires permission to update the team's event types, since a host's limit can reveal their overall booking limit. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_listHosts", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "The `nextCursor` of the previous page.", "schema": { "format": "uuid", "example": "0bce7b70-d7f0-4e5f-bcce-2f41b6fd5116", "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "poolId", "required": true, "in": "path", "description": "Pool UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitPoolHostsOutput" } } } } }, "summary": "List a pool's hosts and their limits", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/booking-limit-pools/{poolId}/hosts/{userId}": { "patch": { "description": "Sets the host's own limit for the intervals sent; null returns that interval to the pool's limit. Only intervals the pool limits can be set, and each is capped at the host's overall booking limit. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_updateHost", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "userId", "required": true, "in": "path", "description": "User UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } }, { "name": "poolId", "required": true, "in": "path", "description": "Pool UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingLimitPoolHostInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitPoolHostResponseOutput" } } } } }, "summary": "Set a host's limit for a pool", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "put": { "description": "Replaces the host's own limit with the intervals sent; an omitted interval returns to the pool's limit, so sending the same body again changes nothing. Only intervals the pool limits can be set, and each is capped at the host's overall booking limit. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_setHost", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "userId", "required": true, "in": "path", "description": "User UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } }, { "name": "poolId", "required": true, "in": "path", "description": "Pool UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBookingLimitPoolHostInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLimitPoolHostResponseOutput" } } } } }, "summary": "Replace a host's limit for a pool", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "delete": { "description": "Returns the host to the pool's limits. If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsBookingLimitPoolsController_clearHost", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "userId", "required": true, "in": "path", "description": "User UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } }, { "name": "poolId", "required": true, "in": "path", "description": "Pool UUID; short UUID form is accepted too.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "" } }, "summary": "Clear a host's limit for a pool", "tags": ["Teams / Booking limit pools"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/bookings": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `booking.readTeamBookings`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_BOOKING_READ` scope is required.", "operationId": "TeamsBookingsController_getAllTeamBookings", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter bookings by status. If you want to filter by multiple statuses, separate them with a comma.", "schema": { "minItems": 1, "example": "?status=upcoming,past", "type": "array", "items": { "type": "string", "enum": ["upcoming", "recurring", "past", "cancelled", "unconfirmed"] } } }, { "name": "attendeeEmail", "required": false, "in": "query", "description": "Filter bookings by the attendee's email address.", "schema": { "example": "example@domain.com", "type": "string" } }, { "name": "attendeeName", "required": false, "in": "query", "description": "Filter bookings by the attendee's name.", "schema": { "example": "John Doe", "type": "string" } }, { "name": "bookingUid", "required": false, "in": "query", "description": "Filter bookings by the booking Uid.", "schema": { "example": "2NtaeaVcKfpmSZ4CthFdfk", "type": "string" } }, { "name": "eventTypeIds", "required": false, "in": "query", "description": "Filter bookings by event type ids. Event type ids must be separated by a comma.", "schema": { "minItems": 1, "example": "?eventTypeIds=100,200", "type": "string" } }, { "name": "eventTypeId", "required": false, "in": "query", "description": "Filter bookings by event type id.", "schema": { "example": "?eventTypeId=100", "type": "string" } }, { "name": "afterStart", "required": false, "in": "query", "description": "Filter bookings with start after this date string.", "schema": { "example": "?afterStart=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeEnd", "required": false, "in": "query", "description": "Filter bookings with end before this date string.", "schema": { "example": "?beforeEnd=2025-03-07T11:00:00.000Z", "type": "string" } }, { "name": "afterCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created after this date string.", "schema": { "example": "?afterCreatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeCreatedAt", "required": false, "in": "query", "description": "Filter bookings that have been created before this date string.", "schema": { "example": "?beforeCreatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "afterUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated after this date string.", "schema": { "example": "?afterUpdatedAt=2025-03-07T10:00:00.000Z", "type": "string" } }, { "name": "beforeUpdatedAt", "required": false, "in": "query", "description": "Filter bookings that have been updated before this date string.", "schema": { "example": "?beforeUpdatedAt=2025-03-14T11:00:00.000Z", "type": "string" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortCreated", "required": false, "in": "query", "description": "Sort results by their creation time (when booking was made) in ascending or descending order.", "schema": { "example": "?sortCreated=asc OR ?sortCreated=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortUpdatedAt", "required": false, "in": "query", "description": "Sort results by their updated time (for example when booking status changes) in ascending or descending order.", "schema": { "example": "?sortUpdatedAt=asc OR ?sortUpdatedAt=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "take", "required": false, "in": "query", "description": "The number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 100, "example": 10, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "The number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBookingsOutput_2024_08_13" } } } } }, "summary": "Get team bookings", "tags": ["Teams / Bookings"], "x-oauth-scopes": ["TEAM_BOOKING_READ"] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}/webhooks": { "post": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesWebhooksController_createTeamEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Create a webhook for a team event type", "tags": ["Teams / Event Types / Webhooks"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "get": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "TeamsEventTypesWebhooksController_getTeamEventTypeWebhooks", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhooksOutputResponseDto" } } } } }, "summary": "Get all webhooks for a team event type", "tags": ["Teams / Event Types / Webhooks"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "delete": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesWebhooksController_deleteAllTeamEventTypeWebhooks", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteManyWebhooksOutputResponseDto" } } } } }, "summary": "Delete all webhooks for a team event type", "tags": ["Teams / Event Types / Webhooks"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/event-types/{eventTypeId}/webhooks/{webhookId}": { "patch": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesWebhooksController_updateTeamEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInputDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Update a webhook for a team event type", "tags": ["Teams / Event Types / Webhooks"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] }, "get": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_READ` scope is required.", "operationId": "TeamsEventTypesWebhooksController_getTeamEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Get a webhook for a team event type", "tags": ["Teams / Event Types / Webhooks"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_READ"] }, "delete": { "description": "If accessed using an OAuth access token, the `TEAM_EVENT_TYPE_WRITE` scope is required.", "operationId": "TeamsEventTypesWebhooksController_deleteTeamEventTypeWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventTypeId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeWebhookOutputResponseDto" } } } } }, "summary": "Delete a webhook for a team event type", "tags": ["Teams / Event Types / Webhooks"], "x-oauth-scopes": ["TEAM_EVENT_TYPE_WRITE"] } }, "/v2/teams/{teamId}/events": { "get": { "description": "Returns every Event the team owns, including ones the authenticated user neither hosts nor co-hosts. The user must be an accepted member of the team, or of its parent organization. PBAC permission: `calEvent.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. Ordered by start time, newest first when `status` is omitted.\n\nCursor-based pagination: pass `pagination.nextCursor` from a previous response as the `cursor` query parameter to fetch the next page; omit `cursor` for the first page. `pagination.hasMore` is `false` and `pagination.nextCursor` is `null` on the last page.\n\nMust pass `cal-api-version: 2026-05-01` (or later). Older versions use `take`/`skip` offset pagination.\n\nEvents are fixed-date RSVP pages served at cal.com/{slug}; they are not event types (bookable meeting templates) or calendar events. If accessed using an OAuth access token, the `TEAM_EVENT_READ` scope is required.", "operationId": "TeamsEventsController_listCursor", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for cursor-based pagination. Pass the `pagination.nextCursor` value from a previous response to fetch the next page. Omit to fetch the first page.", "schema": { "example": "eyJ2IjoyLCJzdGFydFRpbWUiOiIyMDMwLTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJldmVudFR5cGVVdWlkIjoiMDE4ZjRjMmUtM2YxYS03YWJjLTlkZWYtMDEyMzQ1Njc4OWFiIn0", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of Events to return.", "schema": { "minimum": 1, "maximum": 250, "default": 50, "example": 25, "type": "number" } }, { "name": "slug", "required": false, "in": "query", "description": "Filter by the event's public page slug (cal.com/{slug}).", "schema": { "example": "team-offsite", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter events by lifecycle status. `draft`: not published and not cancelled, ordered soonest first. `upcoming`: published and not yet ended, or cancelled but not yet started, ordered soonest first. `past`: everything else, ordered latest first. Omit to return all statuses, newest first. When provided, `pagination.nextCursor` encodes the status — cursors from one status value cannot be used with another and return 400.", "schema": { "example": "upcoming", "type": "string", "enum": ["draft", "upcoming", "past"] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-05-01 (or a later API version) for cursor pagination.", "required": true, "schema": { "type": "string", "example": "2026-05-01", "default": "2026-05-01" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsCursorOutputResponseDto" } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of the team, or insufficient permissions" } }, "summary": "List a team's Events (cursor pagination)", "tags": ["Teams / Events"], "x-oauth-scopes": ["TEAM_EVENT_READ"] }, "post": { "description": "Creates a draft Event owned by the team. A draft is not public and nobody can register until it is published with `POST /v2/events/{uuid}/publish`. The user must be an accepted member of the team, or of its parent organization. PBAC permission: `calEvent.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control.\n\n`startTime` and `endTime` are ISO 8601 in UTC; `startTime` must not be in the past and `endTime` must be after `startTime`.\n\n`guestList` controls whether guests see names, a count, or neither. `locations` sets where the Event happens; set `price` and `currency` on a location to charge for that place.\n\nEvents are fixed-date RSVP pages served at cal.com/{slug}; they are not event types (bookable meeting templates) or calendar events.\n\nIf accessed using an OAuth access token, the `TEAM_EVENT_WRITE` scope is required.", "operationId": "TeamsEventsController_create", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOutputResponseDto" } } } }, "400": { "description": "Invalid input, or a start time in the past" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of the team, or insufficient permissions" } }, "summary": "Create a team Event", "tags": ["Teams / Events"], "x-oauth-scopes": ["TEAM_EVENT_WRITE"] } }, "/v2/teams/{teamId}/invite": { "post": { "description": "Required membership role: `team admin`. PBAC permission: `team.invite`, or `organization.invite` when the team id is an organization. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "TeamsInviteController_createInvite", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteOutputDto" } } } } }, "summary": "Create team invite link", "tags": ["Teams / Invite"], "x-mcp": { "name": "create_team_invite", "guidance": "Generate an invite link for a team. Returns a URL that can be shared with users to join the team." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"] } }, "/v2/teams/{teamId}/memberships": { "post": { "description": "Required membership role: `team admin`. PBAC permission: `team.invite`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "TeamsMembershipsController_createTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamMembershipInput" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamMembershipOutput" } } } } }, "summary": "Create a membership", "tags": ["Teams / Memberships"], "x-mcp": { "name": "create_team_membership", "guidance": "Add a user to a team. Required: userId (must be a real user ID from the system). Optional: role (defaults to MEMBER), accepted, disableImpersonation. accepted: true is applied only to an accepted member of the parent organization or a managed user of the team's OAuth client; anyone else in an organization sub-team is added as a pending invite they have to accept. A team outside an organization can add only managed users of its OAuth client; anyone else returns 403; use create_team_invite to get an invite link for them instead. Ask the user for the userId — never guess." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"] }, "get": { "description": "Retrieve team memberships with optional filtering by email addresses. Supports pagination. Required membership role: `team admin`. PBAC permission: `team.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_READ` scope is required.", "operationId": "TeamsMembershipsController_getTeamMemberships", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "emails", "required": false, "in": "query", "description": "Filter team memberships by email addresses. If you want to filter by multiple emails, separate them with a comma (max 20 emails for performance).", "schema": { "minItems": 1, "maxItems": 20, "example": "?emails=user1@example.com,user2@example.com", "type": "array", "items": { "type": "string", "format": "email" } } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamMembershipsOutput" } } } } }, "summary": "Get all memberships", "tags": ["Teams / Memberships"], "x-mcp": { "name": "get_team_memberships", "guidance": "List all memberships in a team. Supports pagination with take/skip (take max 250) and filtering by up to 20 email addresses." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_READ"] } }, "/v2/teams/{teamId}/memberships/{membershipId}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readMemberships`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_READ` scope is required.", "operationId": "TeamsMembershipsController_getTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamMembershipOutput" } } } } }, "summary": "Get a membership", "tags": ["Teams / Memberships"], "x-mcp": { "name": "get_team_membership", "guidance": "Get a specific team membership by its numeric ID. Use get_team_memberships to find this — never guess." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_READ"] }, "patch": { "description": "Required membership role: `team admin`. PBAC permission: `team.changeMemberRole`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "TeamsMembershipsController_updateTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamMembershipInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamMembershipOutput" } } } } }, "summary": "Update membership", "tags": ["Teams / Memberships"], "x-mcp": { "name": "update_team_membership", "guidance": "Update a team membership. Can change accepted status, role, or impersonation settings. accepted: true on a pending membership is allowed only for an accepted member of the parent organization or a managed user of the team's OAuth client; otherwise it returns 403. Use get_team_memberships to find the membershipId — never guess." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"] }, "delete": { "description": "Required membership role: `team admin`. PBAC permission: `team.remove`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_MEMBERSHIP_WRITE` scope is required.", "operationId": "TeamsMembershipsController_deleteTeamMembership", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "membershipId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTeamMembershipOutput" } } } } }, "summary": "Delete a membership", "tags": ["Teams / Memberships"], "x-mcp": { "name": "delete_team_membership", "guidance": "Remove a user from a team. This action is irreversible — confirm with the user before proceeding. Use get_team_memberships to find the membershipId — never guess." }, "x-oauth-scopes": ["TEAM_MEMBERSHIP_WRITE"] } }, "/v2/teams/{teamId}/routing-forms/{routingFormId}/responses": { "post": { "description": "Only available for teams that are not part of an organization - for a team within an organization use the organization team endpoint instead. Required membership role: `team member`. PBAC permission: `routingForm.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_ROUTING_FORM_WRITE` scope is required.", "operationId": "TeamsRoutingFormsResponsesController_createRoutingFormResponse", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "routingFormId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "start", "required": true, "in": "query", "description": "\n Time starting from which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to start of day or specify hours:\n 2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z\n ", "schema": { "example": "2033-09-05", "type": "string" } }, { "name": "end", "required": true, "in": "query", "description": "\n Time until which available slots should be checked.\n \n Must be in UTC timezone as ISO 8601 datestring.\n \n You can pass date without hours which defaults to end of day or specify hours:\n 2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z", "schema": { "example": "2033-09-06", "type": "string" } }, { "name": "timeZone", "required": false, "in": "query", "description": "Time zone in which the available slots should be returned. Defaults to UTC.", "schema": { "example": "Europe/Rome", "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "If event type has multiple possible durations then you can specify the desired duration here. Also, if you are fetching slots for a dynamic event then you can specify the duration her which defaults to 30, meaning that returned slots will be each 30 minutes long.", "schema": { "example": "60", "type": "number" } }, { "name": "format", "required": false, "in": "query", "description": "Format of slot times in response. Use 'range' to get start and end times.", "schema": { "example": "range", "type": "string", "enum": ["range", "time"] } }, { "name": "bookingUidToReschedule", "required": false, "in": "query", "description": "The unique identifier of the booking being rescheduled. When provided will ensure that the original booking time appears within the returned available slots when rescheduling.", "schema": { "example": "abc123def456", "type": "string" } }, { "name": "rescheduleWithSameHost", "required": false, "in": "query", "description": "Only for round robin event types that allow the person rescheduling to choose the host. True returns slots of the original host, false returns slots of any available host. Ignored for other event types.", "schema": { "example": true, "type": "boolean" } }, { "name": "queueResponse", "required": false, "in": "query", "description": "Whether to queue the form response.", "schema": { "example": true, "type": "boolean" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingFormResponseOutput" } } } } }, "summary": "Create routing form response and get available slots", "tags": ["Teams / Routing forms / Responses"], "x-oauth-scopes": ["TEAM_ROUTING_FORM_WRITE"] } }, "/v2/teams/{teamId}/schedules": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `availability.readTeamAvailability`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_READ` scope is required.", "operationId": "TeamsSchedulesController_getTeamSchedules", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchedulesOutput_2024_06_11" } } } } }, "summary": "Get all team member schedules", "tags": ["Teams / Schedules"], "x-oauth-scopes": ["TEAM_SCHEDULE_READ"] } }, "/v2/teams/{teamId}/users/{userId}/ooo": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `ooo.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_READ` scope is required.", "operationId": "TeamsOOOController_getTeamMemberOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "sortStart", "required": false, "in": "query", "description": "Sort results by their start time in ascending or descending order.", "schema": { "example": "?sortStart=asc OR ?sortStart=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "sortEnd", "required": false, "in": "query", "description": "Sort results by their end time in ascending or descending order.", "schema": { "example": "?sortEnd=asc OR ?sortEnd=desc", "type": "string", "enum": ["asc", "desc"] } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOoosOutputResponseDto" } } } } }, "summary": "Get all out-of-office entries for a team member", "tags": ["Teams / Users / OOO"], "x-oauth-scopes": ["TEAM_SCHEDULE_READ"] }, "post": { "description": "Required membership role: `team admin`. PBAC permission: `ooo.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_WRITE` scope is required.", "operationId": "TeamsOOOController_createTeamMemberOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutOfOfficeEntryDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Create an out-of-office entry for a team member", "tags": ["Teams / Users / OOO"], "x-oauth-scopes": ["TEAM_SCHEDULE_WRITE"] } }, "/v2/teams/{teamId}/users/{userId}/ooo/{oooId}": { "patch": { "description": "Required membership role: `team admin`. PBAC permission: `ooo.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_WRITE` scope is required.", "operationId": "TeamsOOOController_updateTeamMemberOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "oooId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOutOfOfficeEntryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Update an out-of-office entry for a team member", "tags": ["Teams / Users / OOO"], "x-oauth-scopes": ["TEAM_SCHEDULE_WRITE"] }, "delete": { "description": "Required membership role: `team admin`. PBAC permission: `ooo.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_SCHEDULE_WRITE` scope is required.", "operationId": "TeamsOOOController_deleteTeamMemberOOO", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "oooId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOooOutputResponseDto" } } } } }, "summary": "Delete an out-of-office entry for a team member", "tags": ["Teams / Users / OOO"], "x-oauth-scopes": ["TEAM_SCHEDULE_WRITE"] } }, "/v2/teams/{teamId}/verified-resources/emails/verification-code/request": { "post": { "description": "Sends a verification code to the Email. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "TeamsVerifiedResourcesController_requestEmailVerificationCode", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerificationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerificationOutput" } } } } }, "summary": "Request email verification code", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"] } }, "/v2/teams/{teamId}/verified-resources/phones/verification-code/request": { "post": { "description": "Sends a verification code to the phone number. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "TeamsVerifiedResourcesController_requestPhoneVerificationCode", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPhoneVerificationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPhoneVerificationOutput" } } } } }, "summary": "Request phone number verification code", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"] } }, "/v2/teams/{teamId}/verified-resources/emails/verification-code/verify": { "post": { "description": "Use code to verify an email. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "TeamsVerifiedResourcesController_verifyEmail", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedEmailOutput" } } } } }, "summary": "Verify an email for a team", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"] } }, "/v2/teams/{teamId}/verified-resources/phones/verification-code/verify": { "post": { "description": "Use code to verify a phone number. Required membership role: `team admin`. PBAC permission: `team.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "TeamsVerifiedResourcesController_verifyPhoneNumber", "parameters": [ { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPhoneInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedPhoneOutput" } } } } }, "summary": "Verify a phone number for an org team", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_WRITE"] } }, "/v2/teams/{teamId}/verified-resources/emails": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "TeamsVerifiedResourcesController_getVerifiedEmails", "parameters": [ { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedEmailsOutput" } } } } }, "summary": "Get list of verified emails of a team", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"] } }, "/v2/teams/{teamId}/verified-resources/phones": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "TeamsVerifiedResourcesController_getVerifiedPhoneNumbers", "parameters": [ { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedPhonesOutput" } } } } }, "summary": "Get list of verified phone numbers of a team", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"] } }, "/v2/teams/{teamId}/verified-resources/emails/{id}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "TeamsVerifiedResourcesController_getVerifiedEmailById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedEmailOutput" } } } }, "404": { "description": "Verified email not found" } }, "summary": "Get verified email of a team by id", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"] } }, "/v2/teams/{teamId}/verified-resources/phones/{id}": { "get": { "description": "Required membership role: `team admin`. PBAC permission: `team.readVerifiedResources`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `TEAM_VERIFIED_RESOURCES_READ` scope is required.", "operationId": "TeamsVerifiedResourcesController_getVerifiedPhoneById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "teamId", "required": true, "in": "path", "description": "The team's uuid (preferred), its short-uuid (Flickr Base58) form, or its numeric id.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamVerifiedPhoneOutput" } } } }, "404": { "description": "Verified phone number not found" } }, "summary": "Get verified phone number of a team by id", "tags": ["Teams Verified Resources"], "x-oauth-scopes": ["TEAM_VERIFIED_RESOURCES_READ"] } }, "/v2/timezones": { "get": { "description": "Returns the cities Cal.com knows a timezone for, as a `city` to show the user and the IANA `timezone` to store and to send back to Cal.com. Without `search` every city is returned, around 7000 of them.\n\n`search` searches the full source dataset by city name and additionally matches timezone names, so a search for an abbreviation such as `PDT` resolves to `{ \"city\": \"Pacific Time - US & Canada\", \"timezone\": \"America/Los_Angeles\" }`. City and alias names match by case-insensitive substring; complete IANA identifiers also match by case-insensitive equality. Partial IANA identifiers are not matched; timezone matches come first, then cities ordered by population, so the most likely answer is first. City results include `country` and `region` to distinguish same-named cities. Each city name and timezone pair appears once; display the location fields alongside the city and let the user choose. Timezone entries have no `pop`, `country` or `region`.\n\nCal.com stores the IANA identifier, never an abbreviation or an offset: `America/Los_Angeles` already means PDT in summer and PST in winter, and the response has no offset to interpret.", "operationId": "TimezonesController_getTimeZones", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Match city or timezone names by case-insensitive substring, or a complete IANA timezone identifier by case-insensitive equality. Omit it to get every city.", "schema": { "maxLength": 100, "example": "PDT", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Return at most this many entries (a whole number from 1 to 250). Results are ordered by relevance, so a limit keeps the entries a user is most likely to want. Omit it to get every match.", "schema": { "minimum": 1, "maximum": 250, "example": 20, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTimezonesOutput" } } } } }, "summary": "Get timezones", "tags": ["Timezones"], "x-oauth-scopes": [] } }, "/v2/verified-resources/emails/verification-code/request": { "post": { "description": "Sends a verification code to the email. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "UserVerifiedResourcesController_requestEmailVerificationCode", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerificationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerificationOutput" } } } } }, "summary": "Request email verification code", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_WRITE"] } }, "/v2/verified-resources/phones/verification-code/request": { "post": { "description": "Sends a verification code to the phone number. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "UserVerifiedResourcesController_requestPhoneVerificationCode", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPhoneVerificationInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPhoneVerificationOutput" } } } } }, "summary": "Request phone number verification code", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_WRITE"] } }, "/v2/verified-resources/emails/verification-code/verify": { "post": { "description": "Use code to verify an email. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "UserVerifiedResourcesController_verifyEmail", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifiedEmailOutput" } } } } }, "summary": "Verify an email", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_WRITE"] } }, "/v2/verified-resources/phones/verification-code/verify": { "post": { "description": "Use code to verify a phone number. If accessed using an OAuth access token, the `VERIFIED_RESOURCES_WRITE` scope is required.", "operationId": "UserVerifiedResourcesController_verifyPhoneNumber", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPhoneInput" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifiedPhoneOutput" } } } } }, "summary": "Verify a phone number", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_WRITE"] } }, "/v2/verified-resources/emails": { "get": { "description": "If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required.", "operationId": "UserVerifiedResourcesController_getVerifiedEmails", "parameters": [ { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifiedEmailsOutput" } } } } }, "summary": "Get list of verified emails", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_READ"] } }, "/v2/verified-resources/phones": { "get": { "description": "If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required.", "operationId": "UserVerifiedResourcesController_getVerifiedPhoneNumbers", "parameters": [ { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifiedPhonesOutput" } } } } }, "summary": "Get list of verified phone numbers", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_READ"] } }, "/v2/verified-resources/emails/{id}": { "get": { "description": "If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required.", "operationId": "UserVerifiedResourcesController_getVerifiedEmailById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifiedEmailOutput" } } } }, "404": { "description": "Verified email not found" } }, "summary": "Get verified email by id", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_READ"] } }, "/v2/verified-resources/phones/{id}": { "get": { "description": "If accessed using an OAuth access token, the `VERIFIED_RESOURCES_READ` scope is required.", "operationId": "UserVerifiedResourcesController_getVerifiedPhoneById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifiedPhoneOutput" } } } }, "404": { "description": "Verified phone number not found" } }, "summary": "Get verified phone number by id", "tags": ["Verified Resources"], "x-oauth-scopes": ["VERIFIED_RESOURCES_READ"] } }, "/v2/webhooks": { "post": { "description": "If accessed using an OAuth access token, the `WEBHOOK_WRITE` scope is required.", "operationId": "WebhooksController_createWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInputDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhookOutputResponseDto" } } } } }, "summary": "Create a webhook", "tags": ["Webhooks"], "x-oauth-scopes": ["WEBHOOK_WRITE"] }, "get": { "description": "Gets a paginated list of webhooks for the authenticated user. If accessed using an OAuth access token, the `WEBHOOK_READ` scope is required.", "operationId": "WebhooksController_getWebhooks", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhooksOutputResponseDto" } } } } }, "summary": "Get all webhooks", "tags": ["Webhooks"], "x-oauth-scopes": ["WEBHOOK_READ"] } }, "/v2/webhooks/{webhookId}": { "patch": { "description": "If accessed using an OAuth access token, the `WEBHOOK_WRITE` scope is required.", "operationId": "WebhooksController_updateWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInputDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhookOutputResponseDto" } } } } }, "summary": "Update a webhook", "tags": ["Webhooks"], "x-oauth-scopes": ["WEBHOOK_WRITE"] }, "get": { "description": "If accessed using an OAuth access token, the `WEBHOOK_READ` scope is required.", "operationId": "WebhooksController_getWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhookOutputResponseDto" } } } } }, "summary": "Get a webhook", "tags": ["Webhooks"], "x-oauth-scopes": ["WEBHOOK_READ"] }, "delete": { "description": "If accessed using an OAuth access token, the `WEBHOOK_WRITE` scope is required.", "operationId": "WebhooksController_deleteWebhook", "parameters": [ { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhookOutputResponseDto" } } } } }, "summary": "Delete a webhook", "tags": ["Webhooks"], "x-oauth-scopes": ["WEBHOOK_WRITE"] } }, "/v2/workflows": { "get": { "description": "Get the event-type workflows owned by the authenticated user. Routing form workflows are not returned. Not available to third-party OAuth access tokens.", "operationId": "UserWorkflowsController_getWorkflows", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 250, "default": 250, "example": 25, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowsOutput_2026_09_22" } } } } }, "summary": "Get your workflows", "tags": ["Workflows"] }, "post": { "description": "Create an event-type workflow owned by the authenticated user. Not available to third-party OAuth access tokens.", "operationId": "UserWorkflowsController_createWorkflow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventTypeWorkflowDto_2026_09_22" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowOutput_2026_09_22" } } } } }, "summary": "Create a workflow", "tags": ["Workflows"] } }, "/v2/workflows/{workflowId}": { "get": { "description": "Get an event-type workflow owned by the authenticated user. Routing form workflows are not addressable through this endpoint. Not available to third-party OAuth access tokens.", "operationId": "UserWorkflowsController_getWorkflowById", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowOutput_2026_09_22" } } } } }, "summary": "Get your workflow", "tags": ["Workflows"] }, "patch": { "description": "Update an event-type workflow owned by the authenticated user. Not available to third-party OAuth access tokens.", "operationId": "UserWorkflowsController_updateWorkflow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventTypeWorkflowDto_2026_09_22" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventTypeWorkflowOutput_2026_09_22" } } } } }, "summary": "Update your workflow", "tags": ["Workflows"] }, "delete": { "description": "Delete an event-type workflow owned by the authenticated user. Not available to third-party OAuth access tokens.", "operationId": "UserWorkflowsController_deleteWorkflow", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "summary": "Delete your workflow", "tags": ["Workflows"] } }, "/v2/workflows/{workflowId}/condition-fields": { "get": { "description": "List the fields a conditional path on this workflow can be written against, with the comparisons each one accepts and how both read in the Cal.com app. The catalog comes from what the workflow is active on — booking questions on its active event types — so it also reports the entities that do not ask for a field. Not available to third-party OAuth access tokens.", "operationId": "UserWorkflowsController_2026_09_22_getWorkflowConditionFields", "parameters": [ { "name": "cal-api-version", "in": "header", "description": "Must be set to 2026-09-22 to use this version of the workflow endpoints.", "required": true, "schema": { "type": "string", "example": "2026-09-22" } }, { "name": "Authorization", "in": "header", "description": "value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowConditionFieldsOutput" } } } } }, "summary": "Get the fields a workflow's conditions can read", "tags": ["Workflows"] } } }, "info": { "title": "Cal.com API v2", "description": "", "version": "1.0.0", "contact": {} }, "tags": [], "servers": [], "components": { "schemas": { "OAuth2ClientDto": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The OAuth client ID", "example": "clxxxxxxxxxxxxxxxx" }, "redirect_uris": { "description": "The redirect URIs for the OAuth client", "example": ["https://example.com/callback"], "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "description": "The name of the OAuth client", "example": "My App" }, "logo": { "type": "string", "nullable": true, "description": "The logo URL of the OAuth client" }, "is_trusted": { "type": "boolean", "description": "Whether the OAuth client is trusted", "example": false }, "client_type": { "enum": ["CONFIDENTIAL", "PUBLIC"], "type": "string", "description": "The type of OAuth client (CONFIDENTIAL or PUBLIC)", "example": "CONFIDENTIAL" } }, "required": ["client_id", "redirect_uris", "name", "is_trusted", "client_type"] }, "OAuth2ClientResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OAuth2ClientDto" } }, "required": ["status", "data"] }, "OAuth2ExchangeConfidentialInput": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The client identifier", "example": "my-client-id" }, "grant_type": { "type": "string", "description": "The grant type — must be 'authorization_code'", "example": "authorization_code", "enum": ["authorization_code"] }, "code": { "type": "string", "description": "The authorization code received from the authorize endpoint", "example": "abc123" }, "redirect_uri": { "type": "string", "description": "The redirect URI used in the authorization request", "example": "https://example.com/callback" }, "client_secret": { "type": "string", "description": "The client secret for confidential clients" } }, "required": ["client_id", "grant_type", "code", "redirect_uri", "client_secret"] }, "OAuth2ExchangePublicInput": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The client identifier", "example": "my-client-id" }, "grant_type": { "type": "string", "description": "The grant type — must be 'authorization_code'", "example": "authorization_code", "enum": ["authorization_code"] }, "code": { "type": "string", "description": "The authorization code received from the authorize endpoint", "example": "abc123" }, "redirect_uri": { "type": "string", "description": "The redirect URI used in the authorization request", "example": "https://example.com/callback" }, "code_verifier": { "type": "string", "description": "PKCE code verifier (required for public clients that used code_challenge)" } }, "required": ["client_id", "grant_type", "code", "redirect_uri", "code_verifier"] }, "OAuth2RefreshConfidentialInput": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The client identifier", "example": "my-client-id" }, "grant_type": { "type": "string", "description": "The grant type — must be 'refresh_token'", "example": "refresh_token", "enum": ["refresh_token"] }, "refresh_token": { "type": "string", "description": "The refresh token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "client_secret": { "type": "string", "description": "The client secret for confidential clients" } }, "required": ["client_id", "grant_type", "refresh_token", "client_secret"] }, "OAuth2RefreshPublicInput": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The client identifier", "example": "my-client-id" }, "grant_type": { "type": "string", "description": "The grant type — must be 'refresh_token'", "example": "refresh_token", "enum": ["refresh_token"] }, "refresh_token": { "type": "string", "description": "The refresh token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "required": ["client_id", "grant_type", "refresh_token"] }, "OAuth2TokensDto": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "description": "The token type", "example": "bearer" }, "refresh_token": { "type": "string", "description": "The refresh token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "expires_in": { "type": "number", "description": "The number of seconds until the access token expires", "example": 1800 }, "scope": { "type": "string", "description": "The granted scopes (space-delimited per RFC 6749)", "example": "BOOKING_READ BOOKING_WRITE" } }, "required": ["access_token", "token_type", "refresh_token", "expires_in", "scope"] }, "ManagedUserOutput": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "email": { "type": "string", "example": "alice+cluo37fwd0001khkzqqynkpj3@example.com" }, "username": { "type": "string", "nullable": true, "example": "alice" }, "name": { "type": "string", "nullable": true, "example": "alice" }, "bio": { "type": "string", "nullable": true, "example": "bio" }, "timeZone": { "type": "string", "example": "America/New_York" }, "weekStart": { "type": "string", "example": "Sunday" }, "createdDate": { "type": "string", "example": "2024-04-01T00:00:00.000Z", "format": "date-time" }, "timeFormat": { "type": "number", "nullable": true, "example": 12 }, "defaultScheduleId": { "type": "number", "nullable": true, "example": null }, "locale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "avatarUrl": { "type": "string", "nullable": true, "format": "uri", "example": "https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png", "description": "URL of the user's avatar image" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } } }, "required": [ "id", "uuid", "email", "username", "name", "bio", "timeZone", "weekStart", "createdDate", "timeFormat", "defaultScheduleId" ] }, "GetManagedUsersOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedUserOutput" } } }, "required": ["status", "data"] }, "CreateManagedUserInput": { "type": "object", "properties": { "email": { "type": "string", "example": "alice@example.com" }, "name": { "type": "string", "example": "Alice Smith", "description": "Managed user's name is used in emails" }, "timeFormat": { "enum": [12, 24], "type": "number", "example": 12, "description": "Must be a number 12 or 24" }, "weekStart": { "enum": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"], "type": "string", "example": "Monday" }, "timeZone": { "type": "string", "example": "America/New_York", "description": "Timezone is used to create user's default schedule from Monday to Friday from 9AM to 5PM. If it is not passed then user does not have\n a default schedule and it must be created manually via the /schedules endpoint. Until the schedule is created, the user can't access availability atom to set his / her availability nor booked.\n It will default to Europe/London if not passed." }, "locale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "avatarUrl": { "type": "string", "format": "uri", "example": "https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png", "description": "URL of the user's avatar image" }, "bio": { "type": "string", "description": "Bio", "example": "I am a bio" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.", "example": { "key": "value" } } }, "required": ["email", "name"] }, "CreateManagedUserData": { "type": "object", "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, "user": { "$ref": "#/components/schemas/ManagedUserOutput" }, "accessTokenExpiresAt": { "type": "number" }, "refreshTokenExpiresAt": { "type": "number" } }, "required": ["accessToken", "refreshToken", "user", "accessTokenExpiresAt", "refreshTokenExpiresAt"] }, "CreateManagedUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CreateManagedUserData" } }, "required": ["status", "data"] }, "GetManagedUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ManagedUserOutput" } }, "required": ["status", "data"] }, "UpdateManagedUserInput": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "timeFormat": { "enum": [12, 24], "type": "number", "example": 12, "description": "Must be 12 or 24" }, "defaultScheduleId": { "type": "number" }, "weekStart": { "enum": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"], "type": "string", "example": "Monday" }, "timeZone": { "type": "string" }, "locale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "avatarUrl": { "type": "string", "format": "uri", "example": "https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png", "description": "URL of the user's avatar image" }, "bio": { "type": "string", "description": "Bio", "example": "I am a bio" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.", "example": { "key": "value" } } } }, "KeysDto": { "type": "object", "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, "accessTokenExpiresAt": { "type": "number" }, "refreshTokenExpiresAt": { "type": "number" } }, "required": ["accessToken", "refreshToken", "accessTokenExpiresAt", "refreshTokenExpiresAt"] }, "KeysResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/KeysDto" } }, "required": ["status", "data"] }, "CreateOAuthClientInput": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "EVENT_TYPE_READ", "EVENT_TYPE_WRITE", "BOOKING_READ", "BOOKING_WRITE", "SCHEDULE_READ", "SCHEDULE_WRITE", "APPS_READ", "APPS_WRITE", "PROFILE_READ", "PROFILE_WRITE", "*" ] }, "description": "Array of permission keys like [\"BOOKING_READ\", \"BOOKING_WRITE\"]. Use [\"*\"] to grant all permissions." }, "bookingRedirectUri": { "type": "string" }, "bookingCancelRedirectUri": { "type": "string" }, "bookingRescheduleRedirectUri": { "type": "string" }, "areEmailsEnabled": { "type": "boolean" }, "areDefaultEventTypesEnabled": { "type": "boolean", "default": false, "description": "If true, when creating a managed user the managed user will have 4 default event types: 30 and 60 minutes without Cal video, 30 and 60 minutes with Cal video. Set this as false if you want to create a managed user and then manually create event types for the user." }, "areCalendarEventsEnabled": { "type": "boolean", "default": true, "description": "If true and if managed user has calendar connected, calendar events will be created. Disable it if you manually create calendar events. Default to true." } }, "required": ["name", "redirectUris", "permissions"] }, "CreateOAuthClientOutput": { "type": "object", "properties": { "clientId": { "type": "string", "example": "clsx38nbl0001vkhlwin9fmt0" }, "clientSecret": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoib2F1dGgtY2xpZW50Iiwi" } }, "required": ["clientId", "clientSecret"] }, "CreateOAuthClientResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "example": { "clientId": "clsx38nbl0001vkhlwin9fmt0", "clientSecret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoib2F1dGgtY2xpZW50Iiwi" }, "allOf": [ { "$ref": "#/components/schemas/CreateOAuthClientOutput" } ] } }, "required": ["status", "data"] }, "PlatformOAuthClientDto": { "type": "object", "properties": { "id": { "type": "string", "example": "clsx38nbl0001vkhlwin9fmt0" }, "name": { "type": "string", "example": "MyClient" }, "secret": { "type": "string", "example": "secretValue" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "EVENT_TYPE_READ", "EVENT_TYPE_WRITE", "BOOKING_READ", "BOOKING_WRITE", "SCHEDULE_READ", "SCHEDULE_WRITE", "APPS_READ", "APPS_WRITE", "PROFILE_READ", "PROFILE_WRITE" ] }, "description": "Array of permission keys like [\"BOOKING_READ\", \"BOOKING_WRITE\"]", "example": ["BOOKING_READ", "BOOKING_WRITE"] }, "logo": { "type": "string", "nullable": true, "example": "https://example.com/logo.png" }, "redirectUris": { "example": ["https://example.com/callback"], "type": "array", "items": { "type": "string" } }, "organizationId": { "type": "number", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-03-23T08:33:21.851Z" }, "areEmailsEnabled": { "type": "boolean", "example": true }, "areDefaultEventTypesEnabled": { "type": "boolean", "example": true, "description": "If enabled, when creating a managed user the managed user will have 4 default event types: 30 and 60 minutes without Cal video, 30 and 60 minutes with Cal video. Leave this disabled if you want to create a managed user and then manually create event types for the user." }, "areCalendarEventsEnabled": { "type": "boolean", "example": true, "description": "If true and if managed user has calendar connected, calendar events will be created. Disable it if you manually create calendar events. Default to true." }, "bookingRedirectUri": { "type": "string", "format": "uri", "example": "https://example.com/booking-redirect" }, "bookingCancelRedirectUri": { "type": "string", "format": "uri", "example": "https://example.com/booking-cancel" }, "bookingRescheduleRedirectUri": { "type": "string", "format": "uri", "example": "https://example.com/booking-reschedule" } }, "required": [ "id", "name", "secret", "permissions", "redirectUris", "organizationId", "createdAt", "areEmailsEnabled", "areDefaultEventTypesEnabled", "areCalendarEventsEnabled" ] }, "GetOAuthClientsResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformOAuthClientDto" } } }, "required": ["status", "data"] }, "GetOAuthClientResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/PlatformOAuthClientDto" } }, "required": ["status", "data"] }, "UpdateOAuthClientInput": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "bookingRedirectUri": { "type": "string" }, "bookingCancelRedirectUri": { "type": "string" }, "bookingRescheduleRedirectUri": { "type": "string" }, "areEmailsEnabled": { "type": "boolean" }, "areDefaultEventTypesEnabled": { "type": "boolean", "description": "If true, when creating a managed user the managed user will have 4 default event types: 30 and 60 minutes without Cal video, 30 and 60 minutes with Cal video. Set this as false if you want to create a managed user and then manually create event types for the user." }, "areCalendarEventsEnabled": { "type": "boolean", "description": "If true and if managed user has calendar connected, calendar events will be created. Disable it if you manually create calendar events. Default to true." } } }, "RefreshTokenInput": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Managed user's refresh token." } }, "required": ["refreshToken"] }, "RefreshApiKeyInput": { "type": "object", "properties": { "apiKeyDaysValid": { "type": "number", "minimum": 1, "description": "For how many days is managed organization api key valid. Defaults to 30 days.", "example": 60, "default": 30 }, "apiKeyNeverExpires": { "type": "boolean", "description": "If true, organization api key never expires.", "example": true } } }, "ApiKeyOutput": { "type": "object", "properties": { "apiKey": { "type": "string" } }, "required": ["apiKey"] }, "RefreshApiKeyOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ApiKeyOutput" } }, "required": ["status", "data"] }, "SelectedCalendarsInputDto": { "type": "object", "properties": { "integration": { "type": "string" }, "externalId": { "type": "string" }, "credentialId": { "type": "number" }, "delegationCredentialId": { "type": "string" } }, "required": ["integration", "externalId", "credentialId"] }, "SelectedCalendarOutputDto": { "type": "object", "properties": { "userId": { "type": "number" }, "integration": { "type": "string" }, "externalId": { "type": "string" }, "credentialId": { "type": "number", "nullable": true } }, "required": ["userId", "integration", "externalId", "credentialId"] }, "SelectedCalendarOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SelectedCalendarOutputDto" } }, "required": ["status", "data"] }, "StripConnectOutputDto": { "type": "object", "properties": { "authUrl": { "type": "string" } }, "required": ["authUrl"] }, "StripConnectOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/StripConnectOutputDto" } }, "required": ["status", "data"] }, "StripCredentialsSaveOutputResponseDto": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }, "StripCredentialsCheckOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "CalendarInviteTemplateInput_2024_06_14": { "type": "object", "properties": { "mode": { "type": "string", "description": "Template source. `inherit` uses the organization default, `standard` uses Cal.com's standard description, and `custom` uses this object's template.", "enum": ["inherit", "standard", "custom"], "example": "custom" }, "template": { "type": "string", "description": "Custom Markdown description. Required only when mode is custom; maximum length is 5000 characters.", "example": "Meeting with {ATTENDEE} about {LINK_TITLE}" } }, "required": ["mode"] }, "CalendarInvitesInput_2024_06_14": { "type": "object", "properties": { "host": { "description": "Host calendar-invite description settings.", "example": { "mode": "custom", "template": "Meeting with {ATTENDEE}" }, "allOf": [ { "$ref": "#/components/schemas/CalendarInviteTemplateInput_2024_06_14" } ] }, "guest": { "description": "Guest calendar-invite description settings.", "example": { "mode": "inherit" }, "allOf": [ { "$ref": "#/components/schemas/CalendarInviteTemplateInput_2024_06_14" } ] } } }, "BookerLayouts_2024_06_14": { "type": "object", "properties": { "defaultLayout": { "enum": ["month", "week", "column"], "type": "string" }, "enabledLayouts": { "type": "array", "items": { "type": "string", "enum": ["month", "week", "column"] }, "description": "Array of valid layouts - month, week or column" } }, "required": ["defaultLayout", "enabledLayouts"] }, "EmailSettings_2024_06_14": { "type": "object", "properties": { "disableEmailsToAttendees": { "type": "boolean", "description": "Disables all email communication to attendees for this event type, including booking confirmations, reminders, and cancellations. This DOES NOT include emails sent by custom email workflows." }, "disableEmailsToHosts": { "type": "boolean", "description": "Disables all email communication to hosts for this event type, including booking confirmations, reminders, and cancellations. This DOES NOT include emails sent by custom email workflows." }, "disableProposalEmailsToHosts": { "type": "boolean", "description": "Disables only the booking proposal 'choose a time' email sent to hosts for this event type (no one-click confirm links are issued to hosts either). Every other host email - confirmation requests, confirmations, reminders and cancellations - is unaffected. Use this when hosts confirm proposals through an external system." } } }, "EventTypeColor_2024_06_14": { "type": "object", "properties": { "lightThemeHex": { "type": "string", "pattern": "^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$", "description": "Color used for event types in light theme", "example": "#292929" }, "darkThemeHex": { "type": "string", "pattern": "^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$", "description": "Color used for event types in dark theme", "example": "#fafafa" } }, "required": ["lightThemeHex", "darkThemeHex"] }, "DestinationCalendar_2024_06_14": { "type": "object", "properties": { "integration": { "type": "string", "description": "The integration type of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the integration type of your connected calendars." }, "externalId": { "type": "string", "description": "The external ID of the destination calendar. Refer to the /api/v2/calendars endpoint to retrieve the external IDs of your connected calendars." } }, "required": ["integration", "externalId"] }, "InputAddressLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "address", "description": "only allowed value for type is `address`" }, "address": { "type": "string", "minLength": 1, "example": "123 Example St, City, Country" }, "public": { "type": "boolean" } }, "required": ["type", "address", "public"] }, "InputLinkLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "link", "description": "only allowed value for type is `link`" }, "link": { "type": "string", "format": "uri", "example": "https://customvideo.com/join/123456" }, "public": { "type": "boolean" } }, "required": ["type", "link", "public"] }, "InputIntegrationLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "integration", "description": "only allowed value for type is `integration`" }, "integration": { "enum": [ "cal-video", "google-meet", "zoom", "whereby-video", "whatsapp-video", "webex-video", "telegram-video", "tandem", "sylaps-video", "skype-video", "sirius-video", "signal-video", "shimmer-video", "salesroom-video", "roam-video", "riverside-video", "ping-video", "office365-video", "mirotalk-video", "jitsi", "jelly-video", "jelly-conferencing", "huddle", "facetime-video", "element-call-video", "eightxeight-video", "discord-video", "demodesk-video", "campfire-video" ], "type": "string", "example": "cal-video" } }, "required": ["type", "integration"] }, "InputPhoneLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "phone", "description": "only allowed value for type is `phone`" }, "phone": { "type": "string", "example": "+37120993151" }, "public": { "type": "boolean" } }, "required": ["type", "phone", "public"] }, "PhoneFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "phone", "description": "only allowed value for type is `phone`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking. Special slug is `attendeePhoneNumber` - if you create\n a phone input field with this slug for organization team event type you can create an organization team event type that can be booked using phone without requiring an email by setting {\"type\": \"email\", \"required\": false, \"hidden\": true} to the email booking field input in the request body.", "example": "some-slug" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `phone` and the URL contains query parameter `&phone=1234567890`, the phone field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{phone: '+37122222222'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "AddressFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "address", "description": "only allowed value for type is `address`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please enter your address" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "e.g., 1234 Main St" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `address` and the URL contains query parameter `&address=1234 Main St, London`, the address field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{address: 'mainstreat 10, new york'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "TextFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "text", "description": "only allowed value for type is `text`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please enter your text" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "e.g., Enter text here" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `friend` and the URL contains query parameter `&friend=bob`, the text field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{friend: 'bob'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "NumberFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "number", "description": "only allowed value for type is `number`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please enter a number" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "e.g., 100" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `calories` and the URL contains query parameter `&calories=3000`, the number field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{calories: 3000}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "TextAreaFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "textarea", "description": "only allowed value for type is `textarea`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please enter detailed information" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "e.g., Detailed description here..." }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `reflection` and the URL contains query parameter `&reflection=Today I shipped a feature`, the text area will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{reflection: 'Today i shipped a feature'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "SelectFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "select", "description": "only allowed value for type is `select`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please select an option" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "Select..." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `language` and options of this select field are ['english', 'italian'] and the URL contains query parameter `&language=italian`, the 'italian' will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{language: 'italian'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required", "options"] }, "MultiSelectFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "multiselect", "description": "only allowed value for type is `multiselect`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please select multiple options" }, "required": { "type": "boolean" }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `language` and the URL contains query parameter `&language=en&language=it`, the 'en' and 'it' will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{language: ['en', 'it']}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required", "options"] }, "MultiEmailFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "multiemail", "description": "only allowed value for type is `multiemail`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please enter multiple emails" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "e.g., example@example.com" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `consultants` and the URL contains query parameter `&consultants=alice@gmail.com&consultants=bob@gmail.com`, the these emails will be added and none more can be added. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{consultants: ['alice@gmail.com', 'bob@gmail.com']}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "CheckboxGroupFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "checkbox", "description": "only allowed value for type is `checkbox`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Select all that apply" }, "required": { "type": "boolean" }, "options": { "example": ["Checkbox 1", "Checkbox 2"], "type": "array", "items": { "type": "string" } }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `notify` and the URL contains query parameter `¬ify=true`, the checkbox will be selected and the checkbox field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{notify: true}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required", "options"] }, "RadioGroupFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "radio", "description": "only allowed value for type is `radio`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Select one option" }, "required": { "type": "boolean" }, "options": { "example": ["Radio 1", "Radio 2"], "type": "array", "items": { "type": "string" } }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `language` and options of this select field are ['english', 'italian'] and the URL contains query parameter `&language=italian`, the 'italian' radio button will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{language: 'italian'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required", "options"] }, "BooleanFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "boolean", "description": "only allowed value for type is `boolean`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Agree to terms?" }, "required": { "type": "boolean" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `notify` and the URL contains query parameter `¬ify=true`, the checkbox will be selected and the checkbox field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{notify: true}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "UrlFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "url", "description": "only allowed value for type is `url`" }, "slug": { "type": "string", "description": "Unique identifier for the field in format `some-slug`. It is used to access response to this booking field during the booking", "example": "some-slug" }, "label": { "type": "string", "example": "Please enter your text" }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "example": "e.g., Enter url here" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `videourl` and the URL contains query parameter `&videourl=https://youtube.com/abc`the url field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{videourl: 'https://caltube.com/123'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." } }, "required": ["type", "slug", "label", "required"] }, "BusinessDaysWindow_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["businessDays", "calendarDays", "range"], "description": "Whether the window should be business days, calendar days or a range of dates" }, "value": { "type": "number", "example": 5, "description": "How many business day into the future can this event be booked" }, "rolling": { "type": "boolean", "example": true, "description": "\n Determines the behavior of the booking window:\n - If **true**, the window is rolling. This means the number of available days will always be equal the specified 'value' \n and adjust dynamically as bookings are made. For example, if 'value' is 3 and availability is only on Mondays, \n a booker attempting to schedule on November 10 will see slots on November 11, 18, and 25. As one of these days \n becomes fully booked, a new day (e.g., December 2) will open up to ensure 3 available days are always visible.\n In this mode 'value' must be at most 61, because availability is only searched up to 61 days ahead.\n - If **false**, the window is fixed. This means the booking window only considers the next 'value' days from the\n moment someone is trying to book. For example, if 'value' is 3, availability is only on Mondays, and the current \n date is November 10, the booker will only see slots on November 11 because the window is restricted to the next \n 3 calendar days (November 10–12).\n " }, "disabled": { "type": "boolean", "default": false } }, "required": ["type", "value"] }, "CalendarDaysWindow_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["businessDays", "calendarDays", "range"], "description": "Whether the window should be business days, calendar days or a range of dates" }, "value": { "type": "number", "example": 5, "description": "How many calendar days into the future can this event be booked" }, "rolling": { "type": "boolean", "example": true, "description": "\n Determines the behavior of the booking window:\n - If **true**, the window is rolling. This means the number of available days will always be equal the specified 'value' \n and adjust dynamically as bookings are made. For example, if 'value' is 3 and availability is only on Mondays, \n a booker attempting to schedule on November 10 will see slots on November 11, 18, and 25. As one of these days \n becomes fully booked, a new day (e.g., December 2) will open up to ensure 3 available days are always visible.\n In this mode 'value' must be at most 61, because availability is only searched up to 61 days ahead.\n - If **false**, the window is fixed. This means the booking window only considers the next 'value' days from the\n moment someone is trying to book. For example, if 'value' is 3, availability is only on Mondays, and the current \n date is November 10, the booker will only see slots on November 11 because the window is restricted to the next \n 3 calendar days (November 10–12).\n " }, "disabled": { "type": "boolean", "default": false } }, "required": ["type", "value"] }, "RangeWindow_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["businessDays", "calendarDays", "range"], "description": "Whether the window should be business days, calendar days or a range of dates" }, "value": { "minItems": 1, "example": ["2030-09-05", "2030-09-09"], "description": "Date range for when this event can be booked.", "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean", "default": false } }, "required": ["type", "value"] }, "BaseBookingLimitsCount_2024_06_14": { "type": "object", "properties": { "day": { "type": "number", "minimum": 1, "description": "The number of bookings per day", "example": 1 }, "week": { "type": "number", "minimum": 1, "description": "The number of bookings per week", "example": 2 }, "month": { "type": "number", "minimum": 1, "description": "The number of bookings per month", "example": 3 }, "year": { "type": "number", "minimum": 1, "description": "The number of bookings per year", "example": 4 } } }, "BookerActiveBookingsLimit_2024_06_14": { "type": "object", "properties": { "maximumActiveBookings": { "type": "number", "minimum": 1, "description": "The maximum number of active bookings a booker can have for this event type.", "example": 3 }, "offerReschedule": { "type": "boolean", "description": "Whether to offer rescheduling the last active booking to the chosen time slot when limit is reached." }, "disabled": { "type": "boolean", "default": false } } }, "Disabled_2024_06_14": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "Only acceptable value for the `disabled` property is `true`. It is used to reset the value of the property for which previously an object containing specific settings was passed.", "example": true } }, "required": ["disabled"] }, "BaseBookingLimitsDuration_2024_06_14": { "type": "object", "properties": { "day": { "type": "number", "minimum": 15, "description": "The duration of bookings per day (must be a multiple of 15)", "example": 60 }, "week": { "type": "number", "minimum": 15, "description": "The duration of bookings per week (must be a multiple of 15)", "example": 120 }, "month": { "type": "number", "minimum": 15, "description": "The duration of bookings per month (must be a multiple of 15)", "example": 180 }, "year": { "type": "number", "minimum": 15, "description": "The duration of bookings per year (must be a multiple of 15)", "example": 240 }, "disabled": { "type": "boolean", "default": false } } }, "Recurrence_2024_06_14": { "type": "object", "properties": { "interval": { "type": "number", "example": 1, "description": "Repeats every {count} week | month | year", "minimum": 1, "maximum": 20 }, "occurrences": { "type": "number", "example": 10, "description": "Repeats for a maximum of {count} events", "minimum": 1, "maximum": 32 }, "frequency": { "enum": ["yearly", "monthly", "weekly"], "type": "string" }, "disabled": { "type": "boolean", "default": false } }, "required": ["interval", "occurrences", "frequency"] }, "NoticeThreshold_2024_06_14": { "type": "object", "properties": { "unit": { "enum": ["minutes", "hours"], "type": "string", "description": "The unit of time for the notice threshold (e.g., minutes, hours)", "example": "minutes" }, "count": { "type": "number", "description": "The time value for the notice threshold", "example": 30 } }, "required": ["unit", "count"] }, "BaseConfirmationPolicy_2024_06_14": { "type": "object", "properties": { "type": { "enum": ["always", "time"], "type": "string", "description": "The policy that determines when confirmation is required", "example": "always" }, "noticeThreshold": { "description": "The notice threshold required before confirmation is needed. Required when type is 'time'.", "allOf": [ { "$ref": "#/components/schemas/NoticeThreshold_2024_06_14" } ] }, "blockUnconfirmedBookingsInBooker": { "type": "boolean", "description": "Unconfirmed bookings still block calendar slots." }, "disabled": { "type": "boolean", "default": false } }, "required": ["type", "blockUnconfirmedBookingsInBooker"] }, "Seats_2024_06_14": { "type": "object", "properties": { "seatsPerTimeSlot": { "type": "number", "minimum": 1, "description": "Number of seats available per time slot", "example": 4 }, "showAttendeeInfo": { "type": "boolean", "description": "Show attendee information to other guests", "example": true }, "showAvailabilityCount": { "type": "boolean", "description": "Display the count of available seats", "example": true }, "disabled": { "type": "boolean", "default": false } }, "required": ["seatsPerTimeSlot", "showAttendeeInfo", "showAvailabilityCount"] }, "InputAttendeeAddressLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeeAddress", "description": "only allowed value for type is `attendeeAddress`" } }, "required": ["type"] }, "InputAttendeePhoneLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeePhone", "description": "only allowed value for type is `attendeePhone`" } }, "required": ["type"] }, "InputAttendeeDefinedLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeeDefined", "description": "only allowed value for type is `attendeeDefined`" } }, "required": ["type"] }, "NameDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "name", "description": "only allowed value for type is `name`. Used for having 1 booking field for both first name and last name." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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. In case of Booker atom need to pass 'name' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{name: 'bob'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["type"] }, "SplitNameDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "splitName", "description": "only allowed value for type is `splitName`. Used to have 2 booking fields - 1 for first name and 1 for last name." }, "firstNameLabel": { "type": "string" }, "firstNamePlaceholder": { "type": "string" }, "lastNameLabel": { "type": "string" }, "lastNamePlaceholder": { "type": "string" }, "lastNameRequired": { "type": "boolean", "description": "First name field is required but last name field is not by default." }, "disableOnPrefill": { "type": "boolean", "description": "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 `&firstName=bob&lastName=jones`, the first name and last name fields will be prefilled with this value and disabled. In case of Booker atom need to pass 'firstName' and 'lastName' to defaultFormValues prop e.g. `defaultFormValues={{firstName: 'bob', lastName: 'doe'}}` or pass 'name' prop but as a string containing name and surname e.g. `defaultFormValues={{name: 'bob doe'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["type"] }, "EmailDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "email", "description": "only allowed value for type is `email`" }, "label": { "type": "string" }, "required": { "type": "boolean", "default": true, "description": "Pass booking field {type: \"phone\", slug: \"attendeePhoneNumber\", required: true, hidden: false, label: \"whatever label\"} of booking field type PhoneFieldInput_2024_06_14 - this is done\n to enable phone only bookings where during the booking attendee can provide only their phone number and not provide email, so you must pass to the email booking field {hidden: true, required: false}.\n If true show under event type settings but don't show this booking field in the Booker. If false show in both." }, "hidden": { "type": "boolean", "description": "Pass booking field {type: \"phone\", slug: \"attendeePhoneNumber\", required: true, hidden: false, label: \"whatever label\"} of booking field type PhoneFieldInput_2024_06_14 - this is done\n to enable phone only bookings where during the booking attendee can provide only their phone number and not provide email, so you must pass to the email booking field {hidden: true, required: false}.\n If true show under event type settings but don't show this booking field in the Booker. If false show in both." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&email=bob@gmail.com`, the email field will be prefilled with this value and disabled. In case of Booker atom need to pass 'email' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{email: 'bob@gmail.com'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["type"] }, "TitleDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "slug": { "type": "string", "example": "title", "description": "only allowed value for type is `title`" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&title=journey`, the title field will be prefilled with this value and disabled. In case of Booker atom need to pass 'title' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{title: 'very important meeting'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["slug"] }, "LocationDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "slug": { "type": "string", "example": "location", "description": "only allowed value for type is `location`. This booking field is displayed only when event type has 2 or more locations in order to allow person doing the booking pick the location." }, "label": { "type": "string" } }, "required": ["slug"] }, "NotesDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "slug": { "type": "string", "example": "notes", "description": "only allowed value for type is `notes`" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `¬es=journey`, the notes field will be prefilled with this value and disabled. In case of Booker atom need to pass 'notes' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{notes: 'bring notebook and paper'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["slug"] }, "GuestsDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "slug": { "type": "string", "example": "guests", "description": "only allowed value for type is `guests`" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&guests=bob@cal.com`, the guests field will be prefilled with this value and disabled. In case of Booker atom need to pass 'guests' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{guests: ['bob@gmail.com', 'alice@gmail.com']}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["slug"] }, "RescheduleReasonDefaultFieldInput_2024_06_14": { "type": "object", "properties": { "slug": { "type": "string", "example": "rescheduleReason", "description": "only allowed value for type is `rescheduleReason`" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "If true show under event type settings but don't show this booking field in the Booker. If false show in both." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&rescheduleReason=travel`, the rescheduleReason field will be prefilled with this value and disabled. In case of Booker atom need to pass 'rescheduleReason' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{rescheduleReason: 'bob'}}`. See guide https://cal.com/docs/platform/guides/booking-fields" } }, "required": ["slug"] }, "InputOrganizersDefaultApp_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "organizersDefaultApp", "description": "only allowed value for type is `organizersDefaultApp`" } }, "required": ["type"] }, "DisableRescheduling_2024_06_14": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "If true, rescheduling is always disabled for this event type.", "example": true }, "minutesBefore": { "type": "number", "minimum": 1, "description": "Disable rescheduling when less than the specified number of minutes before the meeting. If set, `disabled` should be false or undefined.", "example": 60 } } }, "DisableCancelling_2024_06_14": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "If true, cancelling is always disabled for this event type.", "example": true } } }, "CalVideoSettings": { "type": "object", "properties": { "disableRecordingForOrganizer": { "type": "boolean", "description": "If true, the organizer will not be able to record the meeting", "default": false }, "disableRecordingForGuests": { "type": "boolean", "description": "If true, the guests will not be able to record the meeting", "default": false }, "redirectUrlOnExit": { "type": "string", "nullable": true, "format": "uri", "description": "URL to which participants are redirected when they exit the call" }, "enableAutomaticRecordingForOrganizer": { "type": "boolean", "description": "If true, enables the automatic recording for the event when organizer joins the call", "default": false }, "enableAutomaticTranscription": { "type": "boolean", "description": "If true, enables the automatic transcription for the event whenever someone joins the call", "default": false }, "disableTranscriptionForGuests": { "type": "boolean", "description": "If true, the guests will not be able to receive transcription of the meeting", "default": false }, "disableTranscriptionForOrganizer": { "type": "boolean", "description": "If true, the organizer will not be able to receive transcription of the meeting", "default": false }, "hideTranscriptionForGuests": { "type": "boolean", "description": "If true, guests will not see live transcription captions during the meeting", "default": false }, "hideTranscriptionForOrganizer": { "type": "boolean", "description": "If true, organizers will not see live transcription captions during the meeting", "default": false }, "sendTranscriptionEmails": { "type": "boolean", "description": "Send emails with the transcription of the Cal Video after the meeting ends.", "default": true }, "disableAttendeeRecordingDownloadEmail": { "type": "boolean", "description": "If true, attendees will not receive the Cal Video recording download email for this event type. Defaults to false. Organization guest notifications can still prevent this email from sending.", "default": false }, "transcriptionLanguage": { "type": "string", "nullable": true, "description": "Deepgram language code for transcription (e.g. 'es', 'fr', 'de', 'pt-BR', or 'multi' for auto-detect). Defaults to English when not set.", "enum": [ "multi", "ar", "bg", "ca", "zh-HK", "hr", "cs", "da", "nl", "nl-BE", "fi", "fr", "fr-CA", "de", "de-CH", "el", "he", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "no", "pl", "pt", "pt-BR", "ro", "ru", "sr", "sk", "sl", "es", "es-419", "sv", "th", "tr", "uk", "vi" ] } } }, "PrivateNoteMode": { "type": "string", "enum": ["duplicate_event", "separate_events"], "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites." }, "Host": { "type": "object", "properties": { "userId": { "type": "number", "description": "Which user is the host of this event" }, "mandatory": { "type": "boolean", "default": false, "description": "Only relevant for round robin event types. If true then the user must attend the round robin event always (fixed host). This may be combined with `assignAllTeamMembers: true` on round robin event types — entries marked `mandatory: true` become fixed hosts while every other team member fills the round robin pool." }, "priority": { "default": "medium", "enum": ["lowest", "low", "medium", "high", "highest"], "type": "string" }, "weight": { "type": "number", "minimum": 0, "description": "Only relevant for round robin event types with `isRRWeightsEnabled: true`. Relative share of bookings this host receives - a host with weight 200 gets twice as many bookings as a host with weight 100. Defaults to 100.", "example": 100 } }, "required": ["userId"] }, "CrmAppSettingsInput_2026_06_12": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the CRM app is enabled for this event type, mirroring the event type Apps tab toggle. The credential is resolved server-side — the app must be installed for the event type owner. Omitting this field leaves the app's stored enabled state unchanged and never enables the app." }, "ignoreGuests": { "type": "boolean", "description": "Whether the CRM app ignores guests added to the booking, mirroring the event type Apps tab toggle. Requires the app to be enabled — already enabled for the event type, or send enabled: true in the same request." }, "skipContactCreation": { "type": "boolean", "description": "Whether the CRM app skips creating a contact for the booker, mirroring the event type Apps tab toggle. Requires the app to be enabled — already enabled for the event type, or send enabled: true in the same request." } } }, "CrmSettingsInput_2026_06_12": { "type": "object", "properties": { "hubspot": { "description": "HubSpot app settings for this event type.", "allOf": [ { "$ref": "#/components/schemas/CrmAppSettingsInput_2026_06_12" } ] }, "salesforce": { "description": "Salesforce app settings for this event type.", "allOf": [ { "$ref": "#/components/schemas/CrmAppSettingsInput_2026_06_12" } ] } } }, "CreateTeamEventTypeInput_2026_06_12": { "type": "object", "properties": { "calendarInvites": { "description": "Write-only host and guest calendar-invite description settings. These are saved separately from the event type and are not returned by event-type read endpoints.", "example": { "host": { "mode": "custom", "template": "Meeting with {ATTENDEE}" } }, "allOf": [ { "$ref": "#/components/schemas/CalendarInvitesInput_2024_06_14" } ] }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 60 }, "lengthInMinutesOptions": { "minItems": 1, "uniqueItems": true, "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number", "minimum": 1 } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of the Argentina by making the best flan ever!" }, "slotInterval": { "type": "number", "description": "Number representing length of each slot when event is booked. By default it equal length of the event type.\n If event length is 60 minutes then we would have slots 9AM, 10AM, 11AM etc. but if it was changed to 30 minutes then\n we would have slots 9AM, 9:30AM, 10AM, 10:30AM etc. as the available times to book the 60 minute event." }, "minimumBookingNotice": { "type": "number", "minimum": 0, "description": "Minimum number of minutes before the event that a booking can be made." }, "beforeEventBuffer": { "type": "number", "description": "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." }, "afterEventBuffer": { "type": "number", "description": "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." }, "scheduleId": { "type": "number", "description": "If you want that this event has different schedule than user's default one you can specify it here." }, "bookingLimitsCount": { "description": "Limit how many times this event can be booked", "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "description": "Limit the number of active bookings a booker can make for this event type.", "oneOf": [ { "title": "Active Booking Limit", "$ref": "#/components/schemas/BookerActiveBookingsLimit_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "onlyShowFirstAvailableSlot": { "type": "boolean", "description": "This will limit your availability for this event type to one slot per day, scheduled at the earliest available time." }, "bookingLimitsDuration": { "description": "Limit total amount of time that this event can be booked", "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "description": "Limit how far in the future this event can be booked", "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "offsetStart": { "type": "number", "minimum": 0, "description": "Offset timeslots shown to bookers by a specified number of minutes" }, "bookerLayouts": { "description": "Should booker have week, month or column view. Specify default layout and enabled layouts user can pick.", "allOf": [ { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" } ] }, "confirmationPolicy": { "description": "Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.", "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "recurrence": { "description": "Create a recurring event type.", "oneOf": [ { "title": "Recurring Event", "$ref": "#/components/schemas/Recurrence_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, skips the MX deliverability check for attendee emails on booking. Format validation and watchlist still apply. Requires the editor to belong to an organization (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "description": "Create an event type with multiple seats.", "oneOf": [ { "title": "Seated Event", "$ref": "#/components/schemas/Seats_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "customName": { "type": "string", "description": "Customizable event name with valid variables:\n {Link title}, {Event type title} (legacy), {Organiser}, {Scheduler}, {Location}, {Organiser first name},\n {Scheduler first name}, {Scheduler last name}, {Event duration}, {LOCATION},\n {HOST/ATTENDEE}, {HOST}, {ATTENDEE}, {USER}", "example": "{Link title} between {Organiser} and {Scheduler}" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "successRedirectUrl": { "type": "string", "format": "uri", "description": "A valid URL where the booker will redirect to, once the booking is completed successfully", "example": "https://masterchief.com/argentina/flan/video/9129412" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "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.", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "default": false, "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "example": { "disabled": true }, "allOf": [ { "$ref": "#/components/schemas/DisableCancelling_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "example": { "disabled": false, "minutesBefore": 60 }, "allOf": [ { "$ref": "#/components/schemas/DisableRescheduling_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "description": "Set preferred language for the booking interface. Use empty string for visitor's browser language (default).", "enum": [ "", "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", "sl", "sr", "sv", "tr", "uk", "vi", "zh-CN", "zh-TW" ] }, "weekStart": { "nullable": true, "enum": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], "type": "string", "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only. Omit or set to null to inherit the account setting.", "example": "Monday" }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled.", "default": false }, "allowReschedulingCancelledBookings": { "type": "boolean", "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking.", "default": false }, "showOptimizedSlots": { "type": "boolean", "description": "Arrange time slots to optimize availability.", "default": false }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members.", "default": false }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host.", "default": false }, "privateNoteMode": { "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "example": "duplicate_event", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names.", "example": "Meeting with {Attendee name} for {Link title}" }, "schedulingType": { "enum": ["collective", "roundRobin", "managed"], "type": "string", "example": "collective", "description": "The scheduling type for the team event - collective, roundRobin or managed." }, "hosts": { "description": "Hosts contain specific team members you want to assign to this event type. To assign every current and future team member use `assignAllTeamMembers: true` and omit this field. As an exception, round robin event types accept `hosts` together with `assignAllTeamMembers: true` to mark specific team members as fixed hosts (entries with `mandatory: true`); non-mandatory entries are silently ignored in that combination because they would be added to the round robin pool by `assignAllTeamMembers` anyway. For platform customers the hosts can include userIds only of managed users.", "type": "array", "items": { "$ref": "#/components/schemas/Host" } }, "assignAllTeamMembers": { "type": "boolean", "description": "If true, all current and future team members will be assigned to this event type. Mutually exclusive with `hosts` for collective and managed event types. For round robin event types, `hosts` may be provided alongside `assignAllTeamMembers: true` solely to designate fixed hosts via `mandatory: true` entries." }, "locations": { "type": "array", "description": "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 Cal.com 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.", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/InputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/InputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/InputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/InputPhoneLocation_2024_06_14" }, { "title": "Attendee Address", "$ref": "#/components/schemas/InputAttendeeAddressLocation_2024_06_14" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/InputAttendeePhoneLocation_2024_06_14" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/InputAttendeeDefinedLocation_2024_06_14" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/InputOrganizersDefaultApp_2024_06_14" } ] } }, "rescheduleWithSameRoundRobinHost": { "type": "boolean", "description": "Rescheduled events will be assigned to the same host as initially scheduled." }, "allowRRHostChoiceOnReschedule": { "type": "boolean", "description": "Let the person rescheduling choose between keeping the original host and letting round robin pick from the whole team. Requires rescheduleWithSameRoundRobinHost to be enabled." }, "isRRWeightsEnabled": { "type": "boolean", "description": "Only relevant for round robin event types. If true, bookings are distributed according to each host's `weight` instead of evenly." }, "bookingFields": { "type": "array", "description": "Booking fields for the event type. Omit this property to use the default fields. Provide an array to customize default fields or add custom booking fields. At least one of `email` or `attendeePhoneNumber` must be visible and required. The array cannot be empty, contain duplicate default fields or custom slugs, or use a default field's slug for a custom field. Omitted default fields are added with their default settings. Workflow-added fields are read-only and ignored.", "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] } }, "crm": { "description": "CRM app settings for the event type, mirroring the event type Apps tab toggles. The credential is resolved server-side — the app must be installed for the event type owner.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsInput_2026_06_12" } ] } }, "required": ["lengthInMinutes", "title", "slug", "schedulingType"] }, "SystemFullNameFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "name", "description": "Identifies this as the name default booking field." }, "slug": { "type": "string", "example": "name", "description": "The default name field always uses `name` as its slug." }, "variant": { "type": "string", "example": "fullName", "enum": ["fullName"], "description": "Single full-name input variant." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." } }, "required": ["field", "slug", "variant", "disableOnPrefill"] }, "SystemSplitNameFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "name", "description": "Identifies this as the name default booking field." }, "slug": { "type": "string", "example": "name", "description": "The default name field always uses `name` as its slug." }, "variant": { "type": "string", "example": "splitName", "enum": ["splitName"], "description": "The booking page displays separate fields for the attendee's first and last names." }, "firstNameLabel": { "type": "string" }, "firstNamePlaceholder": { "type": "string" }, "lastNameLabel": { "type": "string" }, "lastNamePlaceholder": { "type": "string" }, "lastNameRequired": { "type": "boolean", "description": "Whether the last name sub-field is required." }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." } }, "required": ["field", "slug", "variant", "lastNameRequired", "disableOnPrefill"] }, "SystemEmailFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "email", "description": "Identifies this as the email default booking field." }, "slug": { "type": "string", "example": "email", "description": "The default email field always uses `email` as its slug." }, "excludeEmails": { "description": "Bookers whose email matches an entry cannot book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } }, "requireEmails": { "description": "Only bookers whose email matches an entry can book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemLocationFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "location", "description": "Identifies this as the location default booking field. The Booker renders the location picker only when the event type has at least 2 location options." }, "slug": { "type": "string", "example": "location", "description": "The default location field always uses `location` as its slug." }, "label": { "type": "string", "example": "Your location default field label" } }, "required": ["field", "slug"] }, "SystemTitleFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "title", "description": "Identifies this as the title default booking field." }, "slug": { "type": "string", "example": "title", "description": "The default booking title field always uses `title` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemNotesFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "notes", "description": "Identifies this as the notes default booking field." }, "slug": { "type": "string", "example": "notes", "description": "The default additional-notes field always uses `notes` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemGuestsFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "guests", "description": "Identifies this as the guests default booking field." }, "slug": { "type": "string", "example": "guests", "description": "The default additional-guests field always uses `guests` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemRescheduleReasonFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "rescheduleReason", "description": "Identifies this as the reschedule reason default booking field." }, "slug": { "type": "string", "example": "rescheduleReason", "description": "The default reschedule-reason field always uses `rescheduleReason` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemAttendeePhoneFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "attendeePhoneNumber", "description": "Identifies this as the attendee phone number default booking field." }, "slug": { "type": "string", "example": "attendeePhoneNumber", "description": "The default attendee phone field always uses `attendeePhoneNumber` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemSmsReminderFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "smsReminderNumber", "description": "Phone-number field added automatically by an SMS workflow." }, "slug": { "type": "string", "example": "smsReminderNumber", "description": "This workflow-added field always uses `smsReminderNumber` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "SystemAiAgentPhoneFieldOutput_2026_06_12": { "type": "object", "properties": { "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string", "example": "Your default field label" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "field": { "type": "string", "example": "aiAgentCallPhoneNumber", "description": "Phone-number field added automatically by an AI-agent workflow." }, "slug": { "type": "string", "example": "aiAgentCallPhoneNumber", "description": "This workflow-added field always uses `aiAgentCallPhoneNumber` as its slug." } }, "required": ["required", "hidden", "disableOnPrefill", "field", "slug"] }, "CustomEmailFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "email", "enum": ["email"], "description": "An email input on the booking page." }, "excludeEmails": { "description": "Bookers whose email matches an entry cannot book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } }, "requireEmails": { "description": "Only bookers whose email matches an entry can book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomPhoneFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "phone", "enum": ["phone"], "description": "A phone-number input on the booking page." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomAddressFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "address", "enum": ["address"], "description": "An address input on the booking page." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomShortTextFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "shortText", "enum": ["shortText"], "description": "A single-line text input on the booking page." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomNumberFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "number", "enum": ["number"], "description": "A number input on the booking page." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomLongTextFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "longText", "enum": ["longText"], "description": "A multi-line text input on the booking page." }, "minLength": { "type": "number", "description": "Minimum character length for the long text field." }, "maxLength": { "type": "number", "description": "Maximum character length for the long text field." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomSelectFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "select", "enum": ["select"], "description": "A dropdown that allows one selection." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "options", "type"] }, "CustomMultiSelectFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "multiSelect", "enum": ["multiSelect"], "description": "A list that allows multiple selections." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "options", "type"] }, "CustomMultiEmailFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "multiEmail", "enum": ["multiEmail"], "description": "An input that accepts multiple email addresses." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomCheckboxGroupFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "checkboxGroup", "enum": ["checkboxGroup"], "description": "A group of checkboxes that allows multiple selections." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "options", "type"] }, "CustomRadioGroupFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "radioGroup", "enum": ["radioGroup"], "description": "A group of radio buttons that allows one selection." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "options", "type"] }, "CustomCheckboxFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "checkbox", "enum": ["checkbox"], "description": "A single checkbox on the booking page." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "CustomUrlFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Identifies this as a custom booking field." }, "slug": { "type": "string", "description": "Unique slug identifier for this custom field.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "url", "enum": ["url"], "description": "A URL input on the booking page." } }, "required": ["field", "slug", "label", "required", "hidden", "disableOnPrefill", "type"] }, "UnknownBookingFieldOutput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "unknown", "enum": ["unknown"] }, "slug": { "type": "string", "example": "unknown", "enum": ["unknown"] }, "bookingField": { "type": "string", "description": "Raw booking-field data that this API version does not recognize." } }, "required": ["field", "slug", "bookingField"] }, "OutputAddressLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "address", "description": "only allowed value for type is `address`" }, "address": { "type": "string", "minLength": 1, "example": "123 Example St, City, Country" }, "public": { "type": "boolean" } }, "required": ["type", "address", "public"] }, "OutputLinkLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "link", "description": "only allowed value for type is `link`" }, "link": { "type": "string", "format": "uri", "example": "https://customvideo.com/join/123456" }, "public": { "type": "boolean" } }, "required": ["type", "link", "public"] }, "OutputIntegrationLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "integration", "description": "Only allowed value for type is `integration`" }, "integration": { "enum": [ "cal-video", "google-meet", "zoom", "whereby-video", "whatsapp-video", "webex-video", "telegram-video", "tandem", "sylaps-video", "skype-video", "sirius-video", "signal-video", "shimmer-video", "salesroom-video", "roam-video", "riverside-video", "ping-video", "office365-video", "mirotalk-video", "jitsi", "jelly-video", "jelly-conferencing", "huddle", "facetime-video", "element-call-video", "eightxeight-video", "discord-video", "demodesk-video", "campfire-video" ], "type": "string", "example": "cal-video" }, "link": { "type": "string", "format": "uri", "example": "https://example.com" }, "credentialId": { "type": "number", "description": "Credential ID associated with the integration" } }, "required": ["type", "integration"] }, "OutputPhoneLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "phone", "description": "only allowed value for type is `phone`" }, "phone": { "type": "string", "example": "+37120993151" }, "public": { "type": "boolean" } }, "required": ["type", "phone", "public"] }, "OutputOrganizersDefaultAppLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "organizersDefaultApp", "description": "only allowed value for type is `organizersDefaultApp`" } }, "required": ["type"] }, "OutputUnknownLocation_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "example": "unknown", "description": "only allowed value for type is `unknown`" }, "location": { "type": "string" } }, "required": ["type", "location"] }, "BookerActiveBookingsLimitOutput_2024_06_14": { "type": "object", "properties": { "maximumActiveBookings": { "type": "number", "minimum": 1, "description": "The maximum number of active bookings a booker can have for this event type.", "example": 3 }, "offerReschedule": { "type": "boolean", "description": "Whether to offer rescheduling the last active booking to the chosen time slot when limit is reached." } } }, "DisableCancellingOutput_2024_06_14": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "If true, cancelling is always disabled for this event type.", "example": true } } }, "DisableReschedulingOutput_2024_06_14": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "If true, rescheduling is always disabled for this event type.", "example": true }, "minutesBefore": { "type": "number", "minimum": 1, "description": "Rescheduling is disabled when less than the specified number of minutes before the meeting.", "example": 60 } } }, "TeamEventTypeResponseHost": { "type": "object", "properties": { "userId": { "type": "number", "description": "Which user is the host of this event" }, "mandatory": { "type": "boolean", "default": false, "description": "Only relevant for round robin event types. If true then the user must attend the round robin event always (fixed host). This may be combined with `assignAllTeamMembers: true` on round robin event types — entries marked `mandatory: true` become fixed hosts while every other team member fills the round robin pool." }, "priority": { "default": "medium", "enum": ["lowest", "low", "medium", "high", "highest"], "type": "string" }, "weight": { "type": "number", "minimum": 0, "description": "Only relevant for round robin event types with `isRRWeightsEnabled: true`. Relative share of bookings this host receives - a host with weight 200 gets twice as many bookings as a host with weight 100. Defaults to 100.", "example": 100 }, "userUuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "description": "The UUID of the host user" }, "name": { "type": "string", "example": "John Doe" }, "username": { "type": "string", "example": "john-doe" }, "avatarUrl": { "type": "string", "nullable": true, "example": "https://cal.com/api/avatar/d95949bc-ccb1-400f-acf6-045c51a16856.png" } }, "required": ["userId", "name", "username"] }, "EventTypeTeam": { "type": "object", "properties": { "id": { "type": "number" }, "slug": { "type": "string" }, "bannerUrl": { "type": "string" }, "name": { "type": "string" }, "logoUrl": { "type": "string" }, "weekStart": { "type": "string" }, "brandColor": { "type": "string" }, "darkBrandColor": { "type": "string" }, "theme": { "type": "string" } }, "required": [ "id", "slug", "bannerUrl", "name", "logoUrl", "weekStart", "brandColor", "darkBrandColor", "theme" ] }, "CrmAppSettingsOutput_2026_06_12": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the CRM app is enabled for this event type." }, "ignoreGuests": { "type": "boolean", "description": "Whether the CRM app ignores guests added to the booking." }, "skipContactCreation": { "type": "boolean", "description": "Whether the CRM app skips creating a contact for the booker." } }, "required": ["enabled", "ignoreGuests", "skipContactCreation"] }, "CrmSettingsOutput_2026_06_12": { "type": "object", "properties": { "hubspot": { "description": "HubSpot app settings for this event type. Present only when the app is configured.", "allOf": [ { "$ref": "#/components/schemas/CrmAppSettingsOutput_2026_06_12" } ] }, "salesforce": { "description": "Salesforce app settings for this event type. Present only when the app is configured.", "allOf": [ { "$ref": "#/components/schemas/CrmAppSettingsOutput_2026_06_12" } ] } } }, "TeamEventTypeOutput_2026_06_12": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "lengthInMinutes": { "type": "number", "example": 60 }, "lengthInMinutesOptions": { "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number" } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of Argentina by making the best flan ever!" }, "locations": { "type": "array", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/OutputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/OutputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/OutputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/OutputPhoneLocation_2024_06_14" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/OutputOrganizersDefaultAppLocation_2024_06_14" }, { "title": "Unknown", "$ref": "#/components/schemas/OutputUnknownLocation_2024_06_14" } ] } }, "disableGuests": { "type": "boolean" }, "slotInterval": { "type": "number", "example": 60, "nullable": true }, "minimumBookingNotice": { "type": "number", "example": 0 }, "beforeEventBuffer": { "type": "number", "example": 0 }, "afterEventBuffer": { "type": "number", "example": 0 }, "recurrence": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/Recurrence_2024_06_14" } ] }, "metadata": { "type": "object", "readOnly": true }, "price": { "type": "number" }, "currency": { "type": "string" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "seatsPerTimeSlot": { "type": "number", "nullable": true }, "forwardParamsSuccessRedirect": { "type": "boolean", "nullable": true }, "successRedirectUrl": { "type": "string", "nullable": true }, "isInstantEvent": { "type": "boolean" }, "seatsShowAvailabilityCount": { "type": "boolean", "nullable": true }, "scheduleId": { "type": "number", "nullable": true }, "bookingLimitsCount": { "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "$ref": "#/components/schemas/BookerActiveBookingsLimitOutput_2024_06_14" }, "onlyShowFirstAvailableSlot": { "type": "boolean" }, "bookingLimitsDuration": { "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "type": "array", "description": "Limit how far in the future this event can be booked", "items": { "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" } ] } }, "bookerLayouts": { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" }, "confirmationPolicy": { "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingProposalCount": { "type": "number", "nullable": true, "description": "Maximum number of timeslots a proposal may include. The client chooses from 1 through this maximum. Null uses the default single-slot booking flow." }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, the MX deliverability check for attendee emails is skipped on booking. Format validation and watchlist still apply. Org-only (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "$ref": "#/components/schemas/Seats_2024_06_14" }, "offsetStart": { "type": "number" }, "customName": { "type": "string" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "Cal video settings for the event type", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "allOf": [ { "$ref": "#/components/schemas/DisableCancellingOutput_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "allOf": [ { "$ref": "#/components/schemas/DisableReschedulingOutput_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "nullable": true, "description": "Set preferred language for the booking interface." }, "weekStart": { "type": "string", "nullable": true, "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only." }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled." }, "allowReschedulingCancelledBookings": { "type": "boolean", "nullable": true, "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking." }, "showOptimizedSlots": { "type": "boolean", "nullable": true, "description": "Arrange time slots to optimize availability." }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members." }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host." }, "privateNoteMode": { "nullable": true, "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "nullable": true, "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names." }, "teamId": { "type": "number" }, "bookingUrl": { "type": "string", "nullable": true, "description": "Full URL to the booking page for this team event type. Null for managed team event types or when the team does not have a slug.", "example": "https://cal.com/team/acme/30min", "format": "uri" }, "ownerId": { "type": "number", "nullable": true }, "parentEventTypeId": { "type": "number", "nullable": true, "description": "For managed event types, parent event type is the event type that this event type is based on" }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/TeamEventTypeResponseHost" } }, "assignAllTeamMembers": { "type": "boolean" }, "schedulingType": { "nullable": true, "type": "string", "enum": ["roundRobin", "collective", "managed"] }, "team": { "$ref": "#/components/schemas/EventTypeTeam" }, "rescheduleWithSameRoundRobinHost": { "type": "boolean", "description": "Rescheduled events will be assigned to the same host as initially scheduled." }, "allowRRHostChoiceOnReschedule": { "type": "boolean", "description": "Let the person rescheduling choose between keeping the original host and letting round robin pick from the whole team." }, "isRRWeightsEnabled": { "type": "boolean", "description": "Only relevant for round robin event types. If true, bookings are distributed according to each host's `weight` instead of evenly." }, "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "The event type's default, custom, and workflow-added booking fields." }, "crm": { "description": "CRM app settings configured for this event type, mirroring the event type Apps tab toggles.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsOutput_2026_06_12" } ] } }, "required": [ "id", "lengthInMinutes", "title", "slug", "description", "locations", "disableGuests", "recurrence", "metadata", "price", "currency", "lockTimeZoneToggleOnBookingPage", "forwardParamsSuccessRedirect", "successRedirectUrl", "isInstantEvent", "scheduleId", "hidden", "bookingRequiresAuthentication", "teamId", "bookingUrl", "hosts", "schedulingType", "team", "bookingFields", "crm" ] }, "CreateTeamEventTypeOutput_2026_06_12": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "oneOf": [ { "title": "Team Event Type", "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" }, { "title": "Team Event Types (array)", "type": "array", "items": { "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" } } ] } }, "required": ["status", "data"] }, "GetTeamEventTypeOutput_2026_06_12": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" } }, "required": ["status", "data"] }, "EventTypeCalendarInviteTemplateOutput": { "type": "object", "properties": { "mode": { "type": "string", "description": "The effective source selected for this event type.", "enum": ["inherit", "standard", "custom"], "example": "custom" }, "template": { "type": "string", "nullable": true, "description": "The event type's custom template, or null when it inherits or uses the standard description.", "example": "Meeting with {ATTENDEE}" }, "organizationTemplate": { "type": "string", "nullable": true, "description": "The organization default template, or null when no organization default is configured.", "example": "Organization default: {LINK_TITLE}" } }, "required": ["mode", "template", "organizationTemplate"] }, "EventTypeCalendarInvitesDataOutput": { "type": "object", "properties": { "host": { "$ref": "#/components/schemas/EventTypeCalendarInviteTemplateOutput" }, "guest": { "$ref": "#/components/schemas/EventTypeCalendarInviteTemplateOutput" }, "readOnly": { "type": "boolean", "description": "Whether this event type is a managed child and its templates are read-only.", "example": false }, "hasOrganization": { "type": "boolean", "description": "Whether this event type resolves through an organization.", "example": true } }, "required": ["host", "guest", "readOnly", "hasOrganization"] }, "EventTypeCalendarInvitesOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventTypeCalendarInvitesDataOutput" } }, "required": ["status", "data"] }, "CalendarInviteTemplateInputDto": { "type": "object", "properties": { "mode": { "type": "string", "description": "Template source. `inherit` uses the organization default, `standard` uses Cal.com's standard description, and `custom` uses this object's template.", "enum": ["inherit", "standard", "custom"], "example": "custom" }, "template": { "type": "string", "description": "Custom Markdown description. Required only when mode is custom; maximum length is 5000 characters.", "example": "Meeting with {ATTENDEE} about {LINK_TITLE}" } }, "required": ["mode"] }, "CalendarInvitesInput": { "type": "object", "properties": { "host": { "description": "Host calendar-invite description settings.", "example": { "mode": "custom", "template": "Meeting with {ATTENDEE}" }, "allOf": [ { "$ref": "#/components/schemas/CalendarInviteTemplateInputDto" } ] }, "guest": { "description": "Guest calendar-invite description settings.", "example": { "mode": "inherit" }, "allOf": [ { "$ref": "#/components/schemas/CalendarInviteTemplateInputDto" } ] } } }, "CreatePhoneCallInput": { "type": "object", "properties": { "yourPhoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Your phone number" }, "numberToCall": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Number to call" }, "calApiKey": { "type": "string", "description": "CAL API Key" }, "enabled": { "type": "boolean", "default": true, "description": "Enabled status" }, "templateType": { "default": "CUSTOM_TEMPLATE", "enum": ["CHECK_IN_APPOINTMENT", "CUSTOM_TEMPLATE"], "type": "string", "description": "Template type" }, "schedulerName": { "type": "string", "description": "Scheduler name" }, "guestName": { "type": "string", "description": "Guest name" }, "guestEmail": { "type": "string", "description": "Guest email" }, "guestCompany": { "type": "string", "description": "Guest company" }, "beginMessage": { "type": "string", "description": "Begin message" }, "generalPrompt": { "type": "string", "description": "General prompt" } }, "required": ["yourPhoneNumber", "numberToCall", "calApiKey", "enabled", "templateType"] }, "Data": { "type": "object", "properties": { "callId": { "type": "string" }, "agentId": { "type": "string" } }, "required": ["callId"] }, "CreatePhoneCallOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/Data" } }, "required": ["status", "data"] }, "GetTeamEventTypesOutput_2026_06_12": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" } } }, "required": ["status", "data"] }, "UpdateTeamEventTypeInput_2026_06_12": { "type": "object", "properties": { "calendarInvites": { "description": "Write-only host and guest calendar-invite description settings. These are saved separately from the event type and are not returned by event-type read endpoints.", "example": { "guest": { "mode": "custom", "template": "Meeting with {ATTENDEE}" } }, "allOf": [ { "$ref": "#/components/schemas/CalendarInvitesInput_2024_06_14" } ] }, "lengthInMinutes": { "type": "number", "example": 60 }, "lengthInMinutesOptions": { "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number" } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of the Argentina by making the best flan ever!" }, "slotInterval": { "type": "number", "description": "Number representing length of each slot when event is booked. By default it equal length of the event type.\n If event length is 60 minutes then we would have slots 9AM, 10AM, 11AM etc. but if it was changed to 30 minutes then\n we would have slots 9AM, 9:30AM, 10AM, 10:30AM etc. as the available times to book the 60 minute event." }, "minimumBookingNotice": { "type": "number", "description": "Minimum number of minutes before the event that a booking can be made." }, "beforeEventBuffer": { "type": "number", "description": "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." }, "afterEventBuffer": { "type": "number", "description": "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." }, "scheduleId": { "type": "number", "description": "If you want that this event has different schedule than user's default one you can specify it here." }, "bookingLimitsCount": { "description": "Limit how many times this event can be booked", "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "description": "Limit the number of active bookings a booker can make for this event type.", "oneOf": [ { "title": "Active Booking Limit", "$ref": "#/components/schemas/BookerActiveBookingsLimit_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "onlyShowFirstAvailableSlot": { "type": "boolean", "description": "This will limit your availability for this event type to one slot per day, scheduled at the earliest available time." }, "bookingLimitsDuration": { "description": "Limit total amount of time that this event can be booked", "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "description": "Limit how far in the future this event can be booked", "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "offsetStart": { "type": "number", "description": "Offset timeslots shown to bookers by a specified number of minutes" }, "bookerLayouts": { "description": "Should booker have week, month or column view. Specify default layout and enabled layouts user can pick.", "allOf": [ { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" } ] }, "confirmationPolicy": { "description": "Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.", "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingProposalCount": { "type": "number", "nullable": true, "description": "Maximum number of timeslots a proposal may include. The client chooses from 1 through this maximum. Set to null to use the default single-slot booking flow." }, "recurrence": { "description": "Create a recurring event type.", "oneOf": [ { "title": "Recurring Event", "$ref": "#/components/schemas/Recurrence_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, skips the MX deliverability check for attendee emails on booking. Format validation and watchlist still apply. Requires the editor to belong to an organization (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "description": "Create an event type with multiple seats.", "oneOf": [ { "title": "Seated Event", "$ref": "#/components/schemas/Seats_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "customName": { "type": "string", "description": "Customizable event name with valid variables:\n {Link title}, {Event type title} (legacy), {Organiser}, {Scheduler}, {Location}, {Organiser first name},\n {Scheduler first name}, {Scheduler last name}, {Event duration}, {LOCATION},\n {HOST/ATTENDEE}, {HOST}, {ATTENDEE}, {USER}", "example": "{Link title} between {Organiser} and {Scheduler}" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "successRedirectUrl": { "type": "string", "description": "A valid URL where the booker will redirect to, once the booking is completed successfully", "example": "https://masterchief.com/argentina/flan/video/9129412" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "Cal video settings for the event type", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "default": false, "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "example": { "disabled": true }, "allOf": [ { "$ref": "#/components/schemas/DisableCancelling_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "example": { "disabled": false, "minutesBefore": 60 }, "allOf": [ { "$ref": "#/components/schemas/DisableRescheduling_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "description": "Set preferred language for the booking interface. Use empty string for visitor's browser language (default).", "enum": [ "", "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", "sl", "sr", "sv", "tr", "uk", "vi", "zh-CN", "zh-TW" ] }, "weekStart": { "type": "string", "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only. Omit or set to null to inherit the account setting.", "enum": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], "example": "Monday" }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled.", "default": false }, "allowReschedulingCancelledBookings": { "type": "boolean", "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking.", "default": false }, "showOptimizedSlots": { "type": "boolean", "description": "Arrange time slots to optimize availability.", "default": false }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members.", "default": false }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host.", "default": false }, "privateNoteMode": { "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "example": "duplicate_event", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names.", "example": "Meeting with {Attendee name} for {Link title}" }, "allowAffectingUpcomingBookings": { "type": "boolean", "description": "Allows this update to affect upcoming bookings when a live confirmation session exists. Not stored and not returned. `true` confirms the edit:\n- Turning seats off cancels every attendee and booking attempt, and new bookings are taken one at a time.\n- Turning confirmation off rejects pending requests, leaves accepted attendees, and confirms new booking attempts until the seats are full.\n- Setting the seat cap below the seats already accepted keeps existing bookings and their seats, and applies the lower cap to new bookings and later confirmations.\n`false` and omitting the field leave the update refused when it would affect upcoming bookings." }, "schedulingType": { "type": "string", "enum": ["collective", "roundRobin"], "example": "collective", "description": "The scheduling type for the team event - collective or roundRobin. ❗If you change scheduling type you must also provide `hosts` or `assignAllTeamMembers` in the request body, otherwise the event type will have no hosts - this is required because\n in case of collective event type all hosts are mandatory but in case of round robin some or non can be mandatory so we can't predict how you want the hosts to be setup which is why you must provide that information. If you want to convert round robin or collective into managed or managed into round robin or collective then you will have to create a new team event type and delete old one." }, "hosts": { "description": "Hosts contain specific team members you want to assign to this event type. To assign every current and future team member use `assignAllTeamMembers: true` and omit this field. As an exception, round robin event types accept `hosts` together with `assignAllTeamMembers: true` to mark specific team members as fixed hosts (entries with `mandatory: true`); non-mandatory entries are silently ignored in that combination because they would be added to the round robin pool by `assignAllTeamMembers` anyway. For platform customers the hosts can include userIds only of managed users.", "type": "array", "items": { "$ref": "#/components/schemas/Host" } }, "assignAllTeamMembers": { "type": "boolean", "description": "If true, all current and future team members will be assigned to this event type. Mutually exclusive with `hosts` for collective and managed event types. For round robin event types, `hosts` may be provided alongside `assignAllTeamMembers: true` solely to designate fixed hosts via `mandatory: true` entries." }, "locations": { "type": "array", "description": "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 Cal.com 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.", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/InputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/InputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/InputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/InputPhoneLocation_2024_06_14" }, { "title": "Attendee Address", "$ref": "#/components/schemas/InputAttendeeAddressLocation_2024_06_14" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/InputAttendeePhoneLocation_2024_06_14" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/InputAttendeeDefinedLocation_2024_06_14" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/InputOrganizersDefaultApp_2024_06_14" } ] } }, "rescheduleWithSameRoundRobinHost": { "type": "boolean", "description": "Rescheduled events will be assigned to the same host as initially scheduled." }, "allowRRHostChoiceOnReschedule": { "type": "boolean", "description": "Let the person rescheduling choose between keeping the original host and letting round robin pick from the whole team. Requires rescheduleWithSameRoundRobinHost to be enabled." }, "isRRWeightsEnabled": { "type": "boolean", "description": "Only relevant for round robin event types. If true, bookings are distributed according to each host's `weight` instead of evenly." }, "bookingFields": { "type": "array", "description": "Booking fields for the event type. Omit this property to keep the current fields. Provide an array to replace them, customize default fields, or add custom booking fields. At least one of `email` or `attendeePhoneNumber` must be visible and required. The array cannot be empty, contain duplicate default fields or custom slugs, or use a default field's slug for a custom field. Omitted default fields are restored with their default settings. Workflow-added fields are read-only and ignored.", "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] } }, "crm": { "description": "CRM app settings for the event type, mirroring the event type Apps tab toggles. The credential is resolved server-side — the app must be installed for the event type owner.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsInput_2026_06_12" } ] } } }, "UpdateTeamEventTypeOutput_2026_06_12": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "oneOf": [ { "title": "Team Event Type", "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" }, { "title": "Team Event Types (array)", "type": "array", "items": { "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" } } ] } }, "required": ["status", "data"] }, "DeletedTeamEventTypeData": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "title": { "type": "string", "example": "Team Meeting" } }, "required": ["id", "title"] }, "DeleteTeamEventTypeOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/DeletedTeamEventTypeData" } }, "required": ["status", "data"] }, "BookingFieldsOutputData_2026_06_12": { "type": "object", "properties": { "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "The event type's default, custom, and workflow-added booking fields." } }, "required": ["bookingFields"] }, "BookingFieldsOutput_2026_06_12": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/BookingFieldsOutputData_2026_06_12" } }, "required": ["status", "data"] }, "SystemFullNameFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "name", "description": "Only allowed value is 'name'." }, "slug": { "type": "string", "example": "name", "description": "Only allowed value is 'name'." }, "variant": { "type": "string", "example": "fullName", "description": "Only allowed value is 'fullName'. Used for having a single booking field for the attendee's full name." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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." } }, "required": ["field", "variant"] }, "SystemSplitNameFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "name", "description": "Only allowed value is 'name'." }, "slug": { "type": "string", "example": "name", "description": "Only allowed value is 'name'." }, "variant": { "type": "string", "example": "splitName", "description": "Only allowed value is 'splitName'. Used to have 2 booking fields — one for first name and one for last name." }, "firstNameLabel": { "type": "string" }, "firstNamePlaceholder": { "type": "string" }, "lastNameLabel": { "type": "string" }, "lastNamePlaceholder": { "type": "string" }, "lastNameRequired": { "type": "boolean", "description": "Whether the last name sub-field is required. The first name sub-field is always required and cannot be configured." }, "disableOnPrefill": { "type": "boolean", "description": "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=John%20Doe`, the first name and last name fields will be prefilled with these values and disabled. The value may also be a JSON object such as `{\"firstName\":\"John\",\"lastName\":\"Doe\"}`." } }, "required": ["field", "variant"] }, "SystemEmailFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "email", "description": "Only allowed value is 'email'." }, "slug": { "type": "string", "example": "email", "description": "Only allowed value is 'email'." }, "label": { "type": "string" }, "required": { "type": "boolean", "description": "To enable phone-only bookings, set this to false and hidden to true, then pass an attendeePhoneNumber default booking field with required: true and hidden: false." }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&email=bob@gmail.com`, the email field will be prefilled with this value and disabled." }, "excludeEmails": { "description": "Bookers whose email matches an entry cannot book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } }, "requireEmails": { "description": "Only bookers whose email matches an entry can book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } } }, "required": ["field"] }, "SystemLocationFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "location", "description": "Only allowed value is 'location'. The Booker renders the location picker only when the event type has at least 2 location options." }, "slug": { "type": "string", "example": "location", "description": "Only allowed value is 'location'." }, "label": { "type": "string" } }, "required": ["field"] }, "SystemTitleFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "title", "description": "Only allowed value is 'title'." }, "slug": { "type": "string", "example": "title", "description": "Only allowed value is 'title'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&title=journey`, the title field will be prefilled with this value and disabled." } }, "required": ["field"] }, "SystemNotesFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "notes", "description": "Only allowed value is 'notes'." }, "slug": { "type": "string", "example": "notes", "description": "Only allowed value is 'notes'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `¬es=bring notebook`, the notes field will be prefilled with this value and disabled." } }, "required": ["field"] }, "SystemGuestsFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "guests", "description": "Only allowed value is 'guests'." }, "slug": { "type": "string", "example": "guests", "description": "Only allowed value is 'guests'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&guests=bob@cal.com`, the guests field will be prefilled with this value and disabled." } }, "required": ["field"] }, "SystemRescheduleReasonFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "rescheduleReason", "description": "Only allowed value is 'rescheduleReason'." }, "slug": { "type": "string", "example": "rescheduleReason", "description": "Only allowed value is 'rescheduleReason'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&rescheduleReason=travel`, the rescheduleReason field will be prefilled with this value and disabled." } }, "required": ["field"] }, "SystemAttendeePhoneFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "attendeePhoneNumber", "description": "Only allowed value is 'attendeePhoneNumber'." }, "slug": { "type": "string", "example": "attendeePhoneNumber", "description": "Only allowed value is 'attendeePhoneNumber'." }, "required": { "type": "boolean", "description": "To enable email-only bookings, set this to false and hidden to true, then pass an email default booking field with required: true and hidden: false." }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&attendeePhoneNumber=+37122222222`, the phone field will be prefilled with this value and disabled." } }, "required": ["field"] }, "SystemSmsReminderFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "smsReminderNumber", "description": "Only allowed value is 'smsReminderNumber'. This field is added automatically by an SMS workflow. It may be echoed from a GET response in create, update, or replace bodies, but the API ignores it; targeted PATCH and DELETE operations reject it." }, "slug": { "type": "string", "example": "smsReminderNumber", "description": "Only allowed value is 'smsReminderNumber'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value." } }, "required": ["field"] }, "SystemAiAgentPhoneFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "aiAgentCallPhoneNumber", "description": "Only allowed value is 'aiAgentCallPhoneNumber'. This field is added automatically by an AI-agent workflow. It may be echoed from a GET response in create, update, or replace bodies, but the API ignores it; targeted PATCH and DELETE operations reject it." }, "slug": { "type": "string", "example": "aiAgentCallPhoneNumber", "description": "Only allowed value is 'aiAgentCallPhoneNumber'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value." } }, "required": ["field"] }, "CustomEmailFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "email", "description": "Only allowed value is 'email'." }, "excludeEmails": { "description": "Bookers whose email matches an entry cannot book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } }, "requireEmails": { "description": "Only bookers whose email matches an entry can book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } } }, "required": ["field", "slug", "label", "type"] }, "CustomPhoneFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "phone", "description": "Only allowed value is 'phone'." } }, "required": ["field", "slug", "label", "type"] }, "CustomAddressFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "address", "description": "Only allowed value is 'address'." } }, "required": ["field", "slug", "label", "type"] }, "CustomShortTextFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "shortText", "description": "Only allowed value is 'shortText'." } }, "required": ["field", "slug", "label", "type"] }, "CustomNumberFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "number", "description": "Only allowed value is 'number'." } }, "required": ["field", "slug", "label", "type"] }, "CustomLongTextFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "longText", "description": "Only allowed value is 'longText'." }, "minLength": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Minimum character length for the long text field. Defaults to 0 if not provided." }, "maxLength": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Maximum character length for the long text field. Defaults to 1000 if not provided." } }, "required": ["field", "slug", "label", "type"] }, "CustomSelectFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "select", "description": "Only allowed value is 'select'." } }, "required": ["field", "slug", "label", "options", "type"] }, "CustomMultiSelectFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "multiSelect", "description": "Only allowed value is 'multiSelect'." } }, "required": ["field", "slug", "label", "options", "type"] }, "CustomMultiEmailFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "multiEmail", "description": "Only allowed value is 'multiEmail'." } }, "required": ["field", "slug", "label", "type"] }, "CustomCheckboxGroupFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "checkboxGroup", "description": "Only allowed value is 'checkboxGroup'." } }, "required": ["field", "slug", "label", "options", "type"] }, "CustomCheckboxFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "checkbox", "description": "Only allowed value is 'checkbox'." } }, "required": ["field", "slug", "label", "type"] }, "CustomRadioGroupFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "radioGroup", "description": "Only allowed value is 'radioGroup'." } }, "required": ["field", "slug", "label", "options", "type"] }, "CustomUrlFieldInput_2026_06_12": { "type": "object", "properties": { "field": { "type": "string", "example": "custom", "description": "Must be 'custom' for all custom booking fields." }, "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "url", "description": "Only allowed value is 'url'." } }, "required": ["field", "slug", "label", "type"] }, "BookingFieldsInput_2026_06_12": { "type": "object", "properties": { "bookingFields": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] }, "description": "Booking fields to add or use as a replacement. The array cannot be empty, contain duplicate default fields or custom slugs, or use a default field's slug for a custom field. When replacing fields, at least one of `email` or `attendeePhoneNumber` must remain visible and required. Workflow-added fields are read-only and ignored when replacing fields." } }, "required": ["bookingFields"] }, "PartialOmitSystemFullNameFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "name", "description": "Only allowed value is 'name'." }, "variant": { "type": "string", "example": "fullName", "description": "Only allowed value is 'fullName'. Used for having a single booking field for the attendee's full name." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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." } } }, "PartialOmitSystemSplitNameFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "name", "description": "Only allowed value is 'name'." }, "variant": { "type": "string", "example": "splitName", "description": "Only allowed value is 'splitName'. Used to have 2 booking fields — one for first name and one for last name." }, "firstNameLabel": { "type": "string" }, "firstNamePlaceholder": { "type": "string" }, "lastNameLabel": { "type": "string" }, "lastNamePlaceholder": { "type": "string" }, "lastNameRequired": { "type": "boolean", "description": "Whether the last name sub-field is required. The first name sub-field is always required and cannot be configured." }, "disableOnPrefill": { "type": "boolean", "description": "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=John%20Doe`, the first name and last name fields will be prefilled with these values and disabled. The value may also be a JSON object such as `{\"firstName\":\"John\",\"lastName\":\"Doe\"}`." } } }, "PartialOmitSystemEmailFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "email", "description": "Only allowed value is 'email'." }, "label": { "type": "string" }, "required": { "type": "boolean", "description": "To enable phone-only bookings, set this to false and hidden to true, then pass an attendeePhoneNumber default booking field with required: true and hidden: false." }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&email=bob@gmail.com`, the email field will be prefilled with this value and disabled." }, "excludeEmails": { "description": "Bookers whose email matches an entry cannot book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } }, "requireEmails": { "description": "Only bookers whose email matches an entry can book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } } } }, "PartialOmitSystemLocationFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "location", "description": "Only allowed value is 'location'." }, "label": { "type": "string" } } }, "PartialOmitSystemTitleFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "title", "description": "Only allowed value is 'title'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&title=journey`, the title field will be prefilled with this value and disabled." } } }, "PartialOmitSystemNotesFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "notes", "description": "Only allowed value is 'notes'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `¬es=bring notebook`, the notes field will be prefilled with this value and disabled." } } }, "PartialOmitSystemGuestsFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "guests", "description": "Only allowed value is 'guests'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&guests=bob@cal.com`, the guests field will be prefilled with this value and disabled." } } }, "PartialOmitSystemRescheduleReasonFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "rescheduleReason", "description": "Only allowed value is 'rescheduleReason'." }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&rescheduleReason=travel`, the rescheduleReason field will be prefilled with this value and disabled." } } }, "PartialOmitSystemAttendeePhoneFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "example": "attendeePhoneNumber", "description": "Only allowed value is 'attendeePhoneNumber'." }, "required": { "type": "boolean", "description": "To enable email-only bookings, set this to false and hidden to true, then pass an email default booking field with required: true and hidden: false." }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 `&attendeePhoneNumber=+37122222222`, the phone field will be prefilled with this value and disabled." } } }, "PartialOmitCustomEmailFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "email", "description": "Only allowed value is 'email'." }, "excludeEmails": { "description": "Bookers whose email matches an entry cannot book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } }, "requireEmails": { "description": "Only bookers whose email matches an entry can book. Entries may be a bare domain (`example.com`), a domain with `@` (`@example.com`), or an exact address (`person@example.com`). Matching is case-insensitive.", "type": "array", "items": { "type": "string" } } } }, "PartialOmitCustomPhoneFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "phone", "description": "Only allowed value is 'phone'." } } }, "PartialOmitCustomAddressFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "address", "description": "Only allowed value is 'address'." } } }, "PartialOmitCustomShortTextFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "shortText", "description": "Only allowed value is 'shortText'." } } }, "PartialOmitCustomNumberFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "number", "description": "Only allowed value is 'number'." } } }, "PartialOmitCustomLongTextFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "longText", "description": "Only allowed value is 'longText'." }, "minLength": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Minimum character length for the long text field. Defaults to 0 if not provided." }, "maxLength": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Maximum character length for the long text field. Defaults to 1000 if not provided." } } }, "PartialOmitCustomSelectFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "select", "description": "Only allowed value is 'select'." } } }, "PartialOmitCustomMultiSelectFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "multiSelect", "description": "Only allowed value is 'multiSelect'." } } }, "PartialOmitCustomMultiEmailFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "multiEmail", "description": "Only allowed value is 'multiEmail'." } } }, "PartialOmitCustomCheckboxGroupFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "checkboxGroup", "description": "Only allowed value is 'checkboxGroup'." } } }, "PartialOmitCustomCheckboxFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "checkbox", "description": "Only allowed value is 'checkbox'." } } }, "PartialOmitCustomRadioGroupFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "options": { "example": ["Option 1", "Option 2"], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "example": "radioGroup", "description": "Only allowed value is 'radioGroup'." } } }, "PartialOmitCustomUrlFieldInput_2026_06_12Field": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the field, e.g. `some-slug`. Can contain letters, numbers, hyphens, and underscores.", "example": "some-slug" }, "label": { "type": "string", "example": "Your custom field label" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Hide this booking field from the booking page while keeping it in the event type's settings. Hidden fields are only returned to callers authorized on the event type." }, "placeholder": { "type": "string" }, "disableOnPrefill": { "type": "boolean", "description": "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 the slug is `my-field` and the URL contains `&my-field=value`, the field will be prefilled with this value and disabled." }, "type": { "type": "string", "example": "url", "description": "Only allowed value is 'url'." } } }, "PatchBookingFieldsInput_2026_06_12": { "type": "object", "properties": { "bookingFields": { "type": "array", "minItems": 1, "items": { "allOf": [ { "type": "object", "required": ["slug"] }, { "anyOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/PartialOmitSystemFullNameFieldInput_2026_06_12Field" }, { "title": "Default Split Name", "$ref": "#/components/schemas/PartialOmitSystemSplitNameFieldInput_2026_06_12Field" }, { "title": "Default Email", "$ref": "#/components/schemas/PartialOmitSystemEmailFieldInput_2026_06_12Field" }, { "title": "Default Location", "$ref": "#/components/schemas/PartialOmitSystemLocationFieldInput_2026_06_12Field" }, { "title": "Default Title", "$ref": "#/components/schemas/PartialOmitSystemTitleFieldInput_2026_06_12Field" }, { "title": "Default Notes", "$ref": "#/components/schemas/PartialOmitSystemNotesFieldInput_2026_06_12Field" }, { "title": "Default Guests", "$ref": "#/components/schemas/PartialOmitSystemGuestsFieldInput_2026_06_12Field" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/PartialOmitSystemRescheduleReasonFieldInput_2026_06_12Field" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/PartialOmitSystemAttendeePhoneFieldInput_2026_06_12Field" }, { "title": "Custom Email", "$ref": "#/components/schemas/PartialOmitCustomEmailFieldInput_2026_06_12Field" }, { "title": "Custom Phone", "$ref": "#/components/schemas/PartialOmitCustomPhoneFieldInput_2026_06_12Field" }, { "title": "Custom Address", "$ref": "#/components/schemas/PartialOmitCustomAddressFieldInput_2026_06_12Field" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/PartialOmitCustomShortTextFieldInput_2026_06_12Field" }, { "title": "Custom Number", "$ref": "#/components/schemas/PartialOmitCustomNumberFieldInput_2026_06_12Field" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/PartialOmitCustomLongTextFieldInput_2026_06_12Field" }, { "title": "Custom Select", "$ref": "#/components/schemas/PartialOmitCustomSelectFieldInput_2026_06_12Field" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/PartialOmitCustomMultiSelectFieldInput_2026_06_12Field" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/PartialOmitCustomMultiEmailFieldInput_2026_06_12Field" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/PartialOmitCustomCheckboxGroupFieldInput_2026_06_12Field" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/PartialOmitCustomCheckboxFieldInput_2026_06_12Field" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/PartialOmitCustomRadioGroupFieldInput_2026_06_12Field" }, { "title": "Custom URL", "$ref": "#/components/schemas/PartialOmitCustomUrlFieldInput_2026_06_12Field" } ] } ] }, "description": "Booking fields to update. Identify each field by `slug` and include at least one property to change. `field` and a custom field's `type` cannot be changed. Null values and repeated slugs are not allowed. Workflow-added fields are read-only." } }, "required": ["bookingFields"] }, "OrgTeamOutputDto": { "type": "object", "properties": { "id": { "type": "number" }, "parentId": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "logoUrl": { "type": "string", "format": "uri" }, "calVideoLogo": { "type": "string", "format": "uri" }, "appLogo": { "type": "string", "format": "uri" }, "appIconLogo": { "type": "string", "format": "uri" }, "bio": { "type": "string" }, "hideBranding": { "type": "boolean" }, "isOrganization": { "type": "boolean" }, "isPrivate": { "type": "boolean" }, "hideBookATeamMember": { "type": "boolean", "default": false }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } }, "theme": { "type": "string" }, "brandColor": { "type": "string" }, "darkBrandColor": { "type": "string" }, "bannerUrl": { "type": "string", "format": "uri" }, "timeFormat": { "type": "number" }, "timeZone": { "type": "string", "default": "Europe/London" }, "weekStart": { "type": "string", "default": "Sunday" } }, "required": ["id", "name", "isOrganization"] }, "OrgTeamsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgTeamOutputDto" } } }, "required": ["status", "data"] }, "OrgMeTeamsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgTeamOutputDto" } } }, "required": ["status", "data"] }, "OrgTeamOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrgTeamOutputDto" } }, "required": ["status", "data"] }, "UpdateOrgTeamDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 155, "description": "Name of the team. Maximum 155 characters. Cannot contain links or URLs.", "example": "CalTeam" }, "slug": { "type": "string", "description": "Team slug", "example": "caltel" }, "logoUrl": { "type": "string", "example": "https://i.cal.com/api/avatar/b0b58752-68ad-4c0d-8024-4fa382a77752.png", "description": "URL of the teams logo image" }, "calVideoLogo": { "type": "string" }, "appLogo": { "type": "string" }, "appIconLogo": { "type": "string" }, "bio": { "type": "string" }, "hideBranding": { "type": "boolean" }, "isPrivate": { "type": "boolean" }, "hideBookATeamMember": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here.\nMetadata must have at most 50 keys, each key up to 40 characters.\nValues can be strings (up to 500 characters), numbers, or booleans.\nReserved team system metadata keys may only be resent with their stored values. Send {} or null to remove custom keys.", "example": { "key": "value" } }, "theme": { "type": "string" }, "brandColor": { "type": "string" }, "darkBrandColor": { "type": "string" }, "bannerUrl": { "type": "string", "example": "https://i.cal.com/api/avatar/949be534-7a88-4185-967c-c020b0c0bef3.png", "description": "URL of the teams banner image which is shown on booker" }, "timeFormat": { "type": "number" }, "timeZone": { "type": "string", "example": "America/New_York", "description": "Timezone is used to create teams's default schedule from Monday to Friday from 9AM to 5PM. It will default to Europe/London if not passed." }, "weekStart": { "type": "string", "example": "Monday" }, "bookingLimits": { "type": "string" }, "includeManagedEventsInLimits": { "type": "boolean" } } }, "CreateOrgTeamDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 155, "description": "Name of the team. Maximum 155 characters. Cannot contain links or URLs.", "example": "CalTeam" }, "slug": { "type": "string", "description": "Team slug in kebab-case - if not provided will be generated automatically based on name.", "example": "caltel" }, "logoUrl": { "type": "string", "example": "https://i.cal.com/api/avatar/b0b58752-68ad-4c0d-8024-4fa382a77752.png", "description": "URL of the teams logo image" }, "calVideoLogo": { "type": "string" }, "appLogo": { "type": "string" }, "appIconLogo": { "type": "string" }, "bio": { "type": "string" }, "hideBranding": { "type": "boolean", "default": false }, "isPrivate": { "type": "boolean" }, "hideBookATeamMember": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here.\nMetadata must have at most 50 keys, each key up to 40 characters.\nValues can be strings (up to 500 characters), numbers, or booleans.\nReserved team system metadata keys are rejected.", "example": { "key": "value" } }, "theme": { "type": "string" }, "brandColor": { "type": "string" }, "darkBrandColor": { "type": "string" }, "bannerUrl": { "type": "string", "example": "https://i.cal.com/api/avatar/949be534-7a88-4185-967c-c020b0c0bef3.png", "description": "URL of the teams banner image which is shown on booker" }, "timeFormat": { "type": "number" }, "timeZone": { "type": "string", "default": "Europe/London", "example": "America/New_York", "description": "Timezone is used to create teams's default schedule from Monday to Friday from 9AM to 5PM. It will default to Europe/London if not passed." }, "weekStart": { "type": "string", "default": "Sunday", "example": "Monday" }, "autoAcceptCreator": { "type": "boolean", "default": true, "description": "If you are a platform customer, don't pass 'false', because then team creator won't be able to create team event types." }, "addCreatorAsOwner": { "type": "boolean", "default": true, "description": "Whether to create an OWNER membership on the team for the user associated with authentication credentials for this request. For example, if you authenticate with API key belonging to Bob, then Bob will have OWNER membership for the newly created team. Pass false to create the team without an OWNER membership for that user - e.g. so it isn't included when assignAllTeamMembers is used on round-robin events. Org admins/owners can still manage the team and its event types without being a team member." } }, "required": ["name"] }, "ScheduleAvailabilityInput_2024_06_11": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string", "enum": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"] }, "example": ["Monday", "Tuesday"], "description": "Array of days when schedule is active." }, "startTime": { "type": "string", "example": "08:00", "description": "startTime must be a valid time in format HH:MM e.g. 08:00" }, "endTime": { "type": "string", "example": "15:00", "description": "endTime must be a valid time in format HH:MM e.g. 15:00" } }, "required": ["days", "startTime", "endTime"] }, "ScheduleOverrideInput_2024_06_11": { "type": "object", "properties": { "date": { "type": "string", "example": "2024-05-20" }, "startTime": { "type": "string", "example": "12:00", "description": "startTime must be a valid time in format HH:MM e.g. 12:00" }, "endTime": { "type": "string", "example": "13:00", "description": "endTime must be a valid time in format HH:MM e.g. 13:00" } }, "required": ["date", "startTime", "endTime"] }, "ScheduleOutput_2024_06_11": { "type": "object", "properties": { "id": { "type": "number", "example": 254 }, "ownerId": { "type": "number", "example": 478 }, "name": { "type": "string", "example": "Catch up hours" }, "timeZone": { "type": "string", "example": "Europe/Rome" }, "availability": { "example": [ { "days": ["Monday", "Tuesday"], "startTime": "17:00", "endTime": "19:00" }, { "days": ["Wednesday", "Thursday"], "startTime": "16:00", "endTime": "20:00" } ], "type": "array", "items": { "$ref": "#/components/schemas/ScheduleAvailabilityInput_2024_06_11" } }, "isDefault": { "type": "boolean", "example": true }, "overrides": { "example": [ { "date": "2024-05-20", "startTime": "18:00", "endTime": "21:00" } ], "type": "array", "items": { "$ref": "#/components/schemas/ScheduleOverrideInput_2024_06_11" } } }, "required": ["id", "ownerId", "name", "timeZone", "availability", "isDefault", "overrides"] }, "GetSchedulesOutput_2024_06_11": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleOutput_2024_06_11" } } }, "required": ["status", "data"] }, "CreateScheduleInput_2024_06_11": { "type": "object", "properties": { "name": { "type": "string", "example": "Catch up hours" }, "timeZone": { "type": "string", "example": "Europe/Rome", "description": "Timezone is used to calculate available times when an event using the schedule is booked." }, "availability": { "description": "Each object contains days and times when the user is available. If not passed, the default availability is Monday to Friday from 09:00 to 17:00.", "example": [ { "days": ["Monday", "Tuesday"], "startTime": "17:00", "endTime": "19:00" }, { "days": ["Wednesday", "Thursday"], "startTime": "16:00", "endTime": "20:00" } ], "type": "array", "items": { "$ref": "#/components/schemas/ScheduleAvailabilityInput_2024_06_11" } }, "isDefault": { "type": "boolean", "example": true, "description": "Each user should have 1 default schedule. If you specified `timeZone` when creating managed user, then the default schedule will be created with that timezone.\n Default schedule means that if an event type is not tied to a specific schedule then the default schedule is used." }, "overrides": { "description": "Need to change availability for a specific date? Add an override.", "example": [ { "date": "2024-05-20", "startTime": "18:00", "endTime": "21:00" } ], "type": "array", "items": { "$ref": "#/components/schemas/ScheduleOverrideInput_2024_06_11" } } }, "required": ["name", "timeZone", "isDefault"] }, "CreateScheduleOutput_2024_06_11": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ScheduleOutput_2024_06_11" } }, "required": ["status", "data"] }, "GetScheduleOutput_2024_06_11": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ScheduleOutput_2024_06_11" } ] } }, "required": ["status", "data"] }, "UpdateScheduleInput_2024_06_11": { "type": "object", "properties": { "name": { "type": "string", "example": "One-on-one coaching" }, "timeZone": { "type": "string", "example": "Europe/Rome" }, "availability": { "example": [ { "days": ["Monday", "Tuesday"], "startTime": "09:00", "endTime": "10:00" } ], "type": "array", "items": { "$ref": "#/components/schemas/ScheduleAvailabilityInput_2024_06_11" } }, "isDefault": { "type": "boolean", "example": true }, "overrides": { "example": [ { "date": "2024-05-20", "startTime": "12:00", "endTime": "14:00" } ], "type": "array", "items": { "$ref": "#/components/schemas/ScheduleOverrideInput_2024_06_11" } } } }, "UpdateScheduleOutput_2024_06_11": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ScheduleOutput_2024_06_11" } }, "required": ["status", "data"] }, "DeleteScheduleOutput_2024_06_11": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "ProfileOutput": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the profile of user", "example": 1 }, "organizationId": { "type": "number", "description": "The ID of the organization of user", "example": 1 }, "userId": { "type": "number", "description": "The IDof the user", "example": 1 }, "username": { "type": "string", "nullable": true, "description": "The username of the user within the organization context", "example": "john_doe" } }, "required": ["id", "organizationId", "userId"] }, "GetOrgUsersWithProfileOutput": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the user", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the user", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "username": { "type": "string", "nullable": true, "description": "The username of the user", "example": "john_doe" }, "name": { "type": "string", "nullable": true, "description": "The name of the user", "example": "John Doe" }, "email": { "type": "string", "description": "The email of the user", "example": "john@example.com" }, "emailVerified": { "format": "date-time", "type": "string", "nullable": true, "description": "The date when the email was verified", "example": "2022-01-01T00:00:00Z" }, "bio": { "type": "string", "nullable": true, "description": "The bio of the user", "example": "I am a software developer" }, "avatarUrl": { "type": "string", "nullable": true, "description": "The URL of the user's avatar", "example": "https://example.com/avatar.jpg" }, "timeZone": { "type": "string", "description": "The time zone of the user", "example": "America/New_York" }, "weekStart": { "type": "string", "description": "The week start day of the user", "example": "Monday" }, "appTheme": { "type": "string", "nullable": true, "description": "The app theme of the user", "example": "light" }, "theme": { "type": "string", "nullable": true, "description": "The theme of the user", "example": "default" }, "defaultScheduleId": { "type": "number", "nullable": true, "description": "The ID of the default schedule for the user", "example": 1 }, "locale": { "type": "string", "nullable": true, "description": "The locale of the user", "example": "en-US" }, "timeFormat": { "type": "number", "nullable": true, "description": "The time format of the user", "example": 12 }, "hideBranding": { "type": "boolean", "description": "Whether to hide branding for the user", "example": false }, "brandColor": { "type": "string", "nullable": true, "description": "The brand color of the user", "example": "#ffffff" }, "darkBrandColor": { "type": "string", "nullable": true, "description": "The dark brand color of the user", "example": "#000000" }, "allowDynamicBooking": { "type": "boolean", "nullable": true, "description": "Whether dynamic booking is allowed for the user", "example": true }, "createdDate": { "format": "date-time", "type": "string", "description": "The date when the user was created", "example": "2022-01-01T00:00:00Z" }, "verified": { "type": "boolean", "nullable": true, "description": "Whether the user is verified", "example": true }, "invitedTo": { "type": "number", "nullable": true, "description": "The ID of the user who invited this user", "example": 1 }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } }, "profile": { "description": "organization user profile, contains user data within the organizaton context", "allOf": [ { "$ref": "#/components/schemas/ProfileOutput" } ] } }, "required": ["id", "uuid", "email", "timeZone", "weekStart", "hideBranding", "createdDate", "profile"] }, "GetOrganizationUsersResponseDTO": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetOrgUsersWithProfileOutput" } } }, "required": ["status", "data"] }, "CreateOrganizationUserInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email address", "example": "user@example.com" }, "username": { "type": "string", "description": "Username", "example": "user123" }, "name": { "type": "string", "minLength": 0, "description": "Full name of the user", "example": "Alice Smith", "maxLength": 50 }, "weekday": { "type": "string", "description": "Preferred weekday", "example": "Monday" }, "brandColor": { "type": "string", "pattern": "^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$", "description": "Brand color in HEX format", "example": "#FFFFFF" }, "bio": { "type": "string", "description": "Bio", "example": "I am a bio" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.", "example": { "key": "value" } }, "darkBrandColor": { "type": "string", "pattern": "^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$", "description": "Dark brand color in HEX format", "example": "#000000" }, "hideBranding": { "type": "boolean", "description": "Hide branding", "example": false }, "timeZone": { "type": "string", "description": "Time zone", "example": "America/New_York" }, "theme": { "type": "string", "nullable": true, "description": "Theme", "example": "dark" }, "appTheme": { "type": "string", "nullable": true, "description": "Application theme", "example": "light" }, "timeFormat": { "type": "number", "description": "Time format", "example": 24 }, "defaultScheduleId": { "type": "number", "minimum": 0, "description": "Default schedule ID", "example": 1 }, "locale": { "type": "string", "nullable": true, "default": "en", "description": "Locale", "example": "en" }, "avatarUrl": { "type": "string", "description": "Avatar URL", "example": "https://example.com/avatar.jpg" }, "organizationRole": { "default": "MEMBER", "enum": ["MEMBER", "ADMIN", "OWNER"], "type": "string" }, "autoAccept": { "type": "boolean", "default": true, "description": "If true, the organization membership is accepted only when the email's domain is the organization's auto-accept domain or one of its verified secondary domains, in a verified organization; any other email gets a pending membership and an invite email. If false, the membership is always pending and the user cannot access the organization until they accept." }, "skipNotificationEmail": { "type": "boolean", "default": false, "description": "If true, the signup notification email will not be sent to the new user." } }, "required": ["email"] }, "OrganizationUserMembershipOutput": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "accepted": { "type": "boolean", "example": false } }, "required": ["id", "accepted"] }, "CreateOrganizationUserData": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the user", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the user", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "username": { "type": "string", "nullable": true, "description": "The username of the user", "example": "john_doe" }, "name": { "type": "string", "nullable": true, "description": "The name of the user", "example": "John Doe" }, "email": { "type": "string", "description": "The email of the user", "example": "john@example.com" }, "emailVerified": { "format": "date-time", "type": "string", "nullable": true, "description": "The date when the email was verified", "example": "2022-01-01T00:00:00Z" }, "bio": { "type": "string", "nullable": true, "description": "The bio of the user", "example": "I am a software developer" }, "avatarUrl": { "type": "string", "nullable": true, "description": "The URL of the user's avatar", "example": "https://example.com/avatar.jpg" }, "timeZone": { "type": "string", "description": "The time zone of the user", "example": "America/New_York" }, "weekStart": { "type": "string", "description": "The week start day of the user", "example": "Monday" }, "appTheme": { "type": "string", "nullable": true, "description": "The app theme of the user", "example": "light" }, "theme": { "type": "string", "nullable": true, "description": "The theme of the user", "example": "default" }, "defaultScheduleId": { "type": "number", "nullable": true, "description": "The ID of the default schedule for the user", "example": 1 }, "locale": { "type": "string", "nullable": true, "description": "The locale of the user", "example": "en-US" }, "timeFormat": { "type": "number", "nullable": true, "description": "The time format of the user", "example": 12 }, "hideBranding": { "type": "boolean", "description": "Whether to hide branding for the user", "example": false }, "brandColor": { "type": "string", "nullable": true, "description": "The brand color of the user", "example": "#ffffff" }, "darkBrandColor": { "type": "string", "nullable": true, "description": "The dark brand color of the user", "example": "#000000" }, "allowDynamicBooking": { "type": "boolean", "nullable": true, "description": "Whether dynamic booking is allowed for the user", "example": true }, "createdDate": { "format": "date-time", "type": "string", "description": "The date when the user was created", "example": "2022-01-01T00:00:00Z" }, "verified": { "type": "boolean", "nullable": true, "description": "Whether the user is verified", "example": true }, "invitedTo": { "type": "number", "nullable": true, "description": "The ID of the user who invited this user", "example": 1 }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } }, "profile": { "description": "organization user profile, contains user data within the organizaton context", "allOf": [ { "$ref": "#/components/schemas/ProfileOutput" } ] }, "membership": { "$ref": "#/components/schemas/OrganizationUserMembershipOutput" } }, "required": [ "id", "uuid", "email", "timeZone", "weekStart", "hideBranding", "createdDate", "profile", "membership" ] }, "CreateOrganizationUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CreateOrganizationUserData" } }, "required": ["status", "data"] }, "UpdateOrganizationUserInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email address", "example": "user@example.com" }, "username": { "type": "string", "description": "Username", "example": "user123" }, "name": { "type": "string", "minLength": 0, "description": "Full name of the user", "example": "Alice Smith", "maxLength": 50 }, "weekday": { "type": "string", "description": "Preferred weekday", "example": "Monday" }, "brandColor": { "type": "string", "pattern": "^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$", "description": "Brand color in HEX format", "example": "#FFFFFF" }, "bio": { "type": "string", "description": "Bio", "example": "I am a bio" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.", "example": { "key": "value" } }, "darkBrandColor": { "type": "string", "pattern": "^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$", "description": "Dark brand color in HEX format", "example": "#000000" }, "hideBranding": { "type": "boolean", "description": "Hide branding", "example": false }, "timeZone": { "type": "string", "description": "Time zone", "example": "America/New_York" }, "theme": { "type": "string", "nullable": true, "description": "Theme", "example": "dark" }, "appTheme": { "type": "string", "nullable": true, "description": "Application theme", "example": "light" }, "timeFormat": { "type": "number", "description": "Time format", "example": 24 }, "defaultScheduleId": { "type": "number", "minimum": 0, "description": "Default schedule ID", "example": 1 }, "locale": { "type": "string", "nullable": true, "default": "en", "description": "Locale", "example": "en" }, "avatarUrl": { "type": "string", "description": "Avatar URL", "example": "https://example.com/avatar.jpg" } } }, "GetOrganizationUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/GetOrgUsersWithProfileOutput" } }, "required": ["status", "data"] }, "BaseAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "TextAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "option": { "type": "string" }, "optionId": { "type": "string" } }, "required": ["id", "name", "type", "option", "optionId"] }, "DateAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["date"], "description": "Identifies a calendar-date attribute assignment." }, "option": { "type": "string", "format": "date", "example": "2026-03-15", "description": "Calendar date in YYYY-MM-DD format, with no time or time zone." }, "optionId": { "type": "string", "description": "ID of the stored attribute option containing this calendar date." } }, "required": ["id", "name", "type", "option", "optionId"] }, "NumberAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "option": { "type": "number" }, "optionId": { "type": "string" } }, "required": ["id", "name", "type", "option", "optionId"] }, "SingleSelectAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "option": { "type": "string" }, "optionId": { "type": "string" } }, "required": ["id", "name", "type", "option", "optionId"] }, "MultiSelectAttributeOption": { "type": "object", "properties": { "optionId": { "type": "string" }, "option": { "type": "string" } }, "required": ["optionId", "option"] }, "MultiSelectAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/MultiSelectAttributeOption" } } }, "required": ["id", "name", "type", "options"] }, "MembershipUserOutputDto": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "avatarUrl": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "bio": { "type": "string" }, "metadata": { "type": "object", "example": { "key": "value" } } }, "required": ["uuid", "email"] }, "OrganizationMembershipOutput": { "type": "object", "properties": { "id": { "type": "number" }, "userId": { "type": "number" }, "teamId": { "type": "number" }, "accepted": { "type": "boolean" }, "role": { "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/MembershipUserOutputDto" }, "attributes": { "type": "array", "items": { "oneOf": [ { "title": "Text", "$ref": "#/components/schemas/TextAttribute" }, { "title": "Date", "$ref": "#/components/schemas/DateAttribute" }, { "title": "Number", "$ref": "#/components/schemas/NumberAttribute" }, { "title": "Single Select", "$ref": "#/components/schemas/SingleSelectAttribute" }, { "title": "Multi-Select", "$ref": "#/components/schemas/MultiSelectAttribute" } ] } } }, "required": ["id", "userId", "teamId", "accepted", "role", "user", "attributes"] }, "GetAllOrgMemberships": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationMembershipOutput" } }, "required": ["status", "data"] }, "CreateOrgMembershipDto": { "type": "object", "properties": { "userId": { "type": "number" }, "accepted": { "type": "boolean", "default": false }, "role": { "default": "MEMBER", "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string", "description": "If you are platform customer then managed users should only have MEMBER role." }, "disableImpersonation": { "type": "boolean", "default": false } }, "required": ["userId", "role"] }, "CreateOrgMembershipByEmailDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email of an existing Cal.com user to invite to the organization." }, "role": { "default": "MEMBER", "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string", "description": "Role to assign to the invited user. If you are platform customer then managed users should only have MEMBER role." } }, "required": ["email", "role"] }, "CreateOrgMembershipOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationMembershipOutput" } }, "required": ["status", "data"] }, "GetOrgMembership": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationMembershipOutput" } }, "required": ["status", "data"] }, "DeleteOrgMembership": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationMembershipOutput" } }, "required": ["status", "data"] }, "UpdateOrgMembershipDto": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "role": { "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean" } } }, "UpdateOrgMembership": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationMembershipOutput" } }, "required": ["status", "data"] }, "OrganizationCalendarInviteTemplateOutput": { "type": "object", "properties": { "mode": { "type": "string", "description": "Whether the organization uses the standard description or its custom default.", "enum": ["inherit", "custom"], "example": "custom" }, "template": { "type": "string", "nullable": true, "description": "The organization default template, or null when the standard description is used.", "example": "Organization default: {LINK_TITLE}" } }, "required": ["mode", "template"] }, "OrganizationCalendarInvitesDataOutput": { "type": "object", "properties": { "host": { "$ref": "#/components/schemas/OrganizationCalendarInviteTemplateOutput" }, "guest": { "$ref": "#/components/schemas/OrganizationCalendarInviteTemplateOutput" } }, "required": ["host", "guest"] }, "OrganizationCalendarInvitesOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationCalendarInvitesDataOutput" } }, "required": ["status", "data"] }, "OrganizationCalendarInviteTemplateInputDto": { "type": "object", "properties": { "mode": { "type": "string", "description": "Use the Cal.com standard description with `inherit`, or set an organization default with `custom`.", "enum": ["inherit", "custom"], "example": "custom" }, "template": { "type": "string", "description": "Custom Markdown description. Required only when mode is custom; maximum length is 5000 characters.", "example": "Meeting with {ATTENDEE} about {LINK_TITLE}" } }, "required": ["mode"] }, "OrganizationCalendarInvitesInput": { "type": "object", "properties": { "host": { "description": "Organization default for host calendar-invite descriptions.", "example": { "mode": "custom", "template": "Meeting with {ATTENDEE}" }, "allOf": [ { "$ref": "#/components/schemas/OrganizationCalendarInviteTemplateInputDto" } ] }, "guest": { "description": "Organization default for guest calendar-invite descriptions.", "example": { "mode": "inherit" }, "allOf": [ { "$ref": "#/components/schemas/OrganizationCalendarInviteTemplateInputDto" } ] } } }, "TeamMembershipOutput": { "type": "object", "properties": { "id": { "type": "number" }, "userId": { "type": "number" }, "teamId": { "type": "number" }, "accepted": { "type": "boolean" }, "role": { "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/MembershipUserOutputDto" } }, "required": ["id", "userId", "teamId", "accepted", "role", "user"] }, "OrgTeamMembershipsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMembershipOutput" } } }, "required": ["status", "data"] }, "OrgTeamMembershipOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamMembershipOutput" } }, "required": ["status", "data"] }, "UpdateOrgTeamMembershipDto": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "role": { "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean" } } }, "CreateOrgTeamMembershipDto": { "type": "object", "properties": { "userId": { "type": "number" }, "accepted": { "type": "boolean", "default": false }, "role": { "default": "MEMBER", "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean", "default": false } }, "required": ["userId", "role"] }, "InviteDataDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Unique invitation token for this team. Share this token with prospective members to allow them to join the team/organization.", "example": "f6a5c8b1d2e34c7f90a1b2c3d4e5f6a5b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2" }, "inviteLink": { "type": "string", "description": "Complete invitation URL that can be shared with prospective members. Opens the signup page with the token and redirects to getting started after signup.", "example": "http://app.cal.com/signup?token=f6a5c8b1d2e34c7f90a1b2c3d4e5f6a5b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2&callbackUrl=/getting-started" } }, "required": ["token", "inviteLink"] }, "CreateInviteOutputDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/InviteDataDto" } }, "required": ["status", "data"] }, "RuleEvaluationOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the rule evaluation" }, "runId": { "type": "string", "description": "ID of the parent sync run" }, "ruleId": { "type": "string", "nullable": true, "description": "ID of the matching rule, if any" }, "evaluationOrder": { "type": "number", "description": "Order in which this rule was evaluated" }, "attributeKey": { "type": "string", "description": "Attribute key that was evaluated" }, "operator": { "type": "string", "description": "Comparison operator used (e.g. EQUALS, CONTAINS)" }, "expectedValue": { "type": "string", "nullable": true, "description": "Value the rule expected to match" }, "expectedValueType": { "type": "string", "description": "Data type of the expected value" }, "actualValue": { "type": "string", "nullable": true, "description": "Actual value from the external provider" }, "actualValueType": { "type": "string", "description": "Data type of the actual value" }, "passed": { "type": "boolean", "description": "Whether the rule condition was satisfied" }, "createdAt": { "type": "string", "description": "When this evaluation was recorded" } }, "required": [ "id", "runId", "evaluationOrder", "attributeKey", "operator", "expectedValueType", "actualValueType", "passed", "createdAt" ] }, "FieldMappingAppliedOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the field mapping application" }, "runId": { "type": "string", "description": "ID of the parent sync run" }, "fieldMappingId": { "type": "string", "nullable": true, "description": "ID of the field mapping configuration" }, "attributeId": { "type": "string", "nullable": true, "description": "ID of the Cal.com attribute that was updated" }, "attributeSlug": { "type": "string", "description": "Slug of the Cal.com attribute" }, "attributeName": { "type": "string", "description": "Display name of the Cal.com attribute" }, "sourceField": { "type": "string", "description": "Source field name from the external provider" }, "previousValue": { "type": "string", "nullable": true, "description": "Attribute value before the sync" }, "newValue": { "type": "string", "nullable": true, "description": "Attribute value after the sync" }, "outcome": { "type": "string", "description": "Outcome of the mapping (e.g. CREATED, UPDATED, UNCHANGED)" }, "createdAt": { "type": "string", "description": "When this mapping was applied" } }, "required": ["id", "runId", "attributeSlug", "attributeName", "sourceField", "outcome", "createdAt"] }, "TeamMembershipChangeOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the membership change" }, "runId": { "type": "string", "description": "ID of the parent sync run" }, "teamId": { "type": "number", "nullable": true, "description": "Cal.com team ID affected by this change" }, "teamName": { "type": "string", "description": "Name of the team" }, "teamSlug": { "type": "string", "nullable": true, "description": "Slug of the team" }, "outcome": { "type": "string", "description": "Outcome of the change (e.g. ADDED, REMOVED, NO_CHANGE)" }, "createdAt": { "type": "string", "description": "When this membership change was recorded" } }, "required": ["id", "runId", "teamName", "outcome", "createdAt"] }, "IntegrationSyncRunWithChildrenOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the sync run" }, "provider": { "type": "string", "description": "Integration provider (e.g. SALESFORCE)" }, "credentialId": { "type": "number", "nullable": true, "description": "Credential ID that triggered the sync" }, "organizationId": { "type": "number", "nullable": true, "description": "Organization ID" }, "userId": { "type": "number", "nullable": true, "description": "Cal.com user ID affected by this sync" }, "userName": { "type": "string", "nullable": true, "description": "Display name of the affected user" }, "externalUserId": { "type": "string", "nullable": true, "description": "External provider user identifier" }, "status": { "type": "string", "description": "Status of the sync run", "enum": [ "APPLIED", "SKIPPED_BY_RULE", "NO_RULES_MATCHED", "FAILED", "INVALID_SIGNATURE", "RATE_LIMITED" ] }, "signatureVerified": { "type": "boolean", "description": "Whether the inbound webhook signature was verified" }, "errorMessage": { "type": "string", "nullable": true, "description": "Error message if the sync failed" }, "createdAt": { "type": "string", "description": "When this sync run was recorded" }, "ruleEvaluations": { "description": "Rules evaluated during this sync run", "type": "array", "items": { "$ref": "#/components/schemas/RuleEvaluationOutput" } }, "appliedFieldMappings": { "description": "Field mappings applied during this sync run", "type": "array", "items": { "$ref": "#/components/schemas/FieldMappingAppliedOutput" } }, "teamMembershipChanges": { "description": "Team membership changes resulting from this sync run", "type": "array", "items": { "$ref": "#/components/schemas/TeamMembershipChangeOutput" } } }, "required": [ "id", "provider", "status", "signatureVerified", "createdAt", "ruleEvaluations", "appliedFieldMappings", "teamMembershipChanges" ] }, "PaginationMeta": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more pages are available" }, "nextCursor": { "type": "string", "description": "Cursor for the next page, if available" } }, "required": ["hasMore"] }, "GetAttributeSyncHistoryOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSyncRunWithChildrenOutput" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": ["status", "data", "meta"] }, "Attribute": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the attribute", "example": "attr_123" }, "teamId": { "type": "number", "description": "The team ID associated with the attribute", "example": 1 }, "type": { "enum": ["TEXT", "NUMBER", "DATE", "SINGLE_SELECT", "MULTI_SELECT", "USER_RELATIONSHIP"], "type": "string", "description": "The type of the attribute" }, "name": { "type": "string", "description": "The name of the attribute", "example": "Attribute Name" }, "slug": { "type": "string", "description": "The slug of the attribute", "example": "attribute-name" }, "enabled": { "type": "boolean", "description": "Whether the attribute is enabled and displayed on their profile", "example": true }, "usersCanEditRelation": { "type": "boolean", "description": "Whether users can edit the relation", "example": true } }, "required": ["id", "teamId", "type", "name", "slug", "enabled"] }, "GetOrganizationAttributesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } }, "required": ["status", "data"] }, "GetSingleAttributeOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/Attribute" } ] } }, "required": ["status", "data"] }, "CreateOrganizationAttributeOptionInput": { "type": "object", "properties": { "value": { "type": "string" }, "slug": { "type": "string" } }, "required": ["value", "slug"] }, "CreateOrganizationAttributeInput": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "enum": ["TEXT", "NUMBER", "DATE", "SINGLE_SELECT", "MULTI_SELECT", "USER_RELATIONSHIP"], "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/CreateOrganizationAttributeOptionInput" } }, "enabled": { "type": "boolean" } }, "required": ["name", "slug", "type", "options"] }, "CreateOrganizationAttributesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/Attribute" } }, "required": ["status", "data"] }, "UpdateOrganizationAttributeInput": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "enum": ["TEXT", "NUMBER", "DATE", "SINGLE_SELECT", "MULTI_SELECT", "USER_RELATIONSHIP"], "type": "string" }, "enabled": { "type": "boolean" } } }, "UpdateOrganizationAttributesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/Attribute" } }, "required": ["status", "data"] }, "DeleteOrganizationAttributesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/Attribute" } }, "required": ["status", "data"] }, "OptionOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the option", "example": "attr_option_id" }, "attributeId": { "type": "string", "description": "The ID of the attribute", "example": "attr_id" }, "value": { "type": "string", "description": "The value of the option", "example": "option_value" }, "slug": { "type": "string", "description": "The slug of the option", "example": "option-slug" } }, "required": ["id", "attributeId", "value", "slug"] }, "CreateAttributeOptionOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OptionOutput" } }, "required": ["status", "data"] }, "DeleteAttributeOptionOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OptionOutput" } }, "required": ["status", "data"] }, "UpdateOrganizationAttributeOptionInput": { "type": "object", "properties": { "value": { "type": "string" }, "slug": { "type": "string" } } }, "UpdateAttributeOptionOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OptionOutput" } }, "required": ["status", "data"] }, "GetAllAttributeOptionOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OptionOutput" } } }, "required": ["status", "data"] }, "AssignedOptionOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the option", "example": "attr_option_id" }, "attributeId": { "type": "string", "description": "The ID of the attribute", "example": "attr_id" }, "value": { "type": "string", "description": "The value of the option", "example": "option_value" }, "slug": { "type": "string", "description": "The slug of the option", "example": "option-slug" }, "assignedUserIds": { "description": "Ids of the users assigned to the attribute option.", "example": [124, 224], "type": "array", "items": { "type": "number" } } }, "required": ["id", "attributeId", "value", "slug", "assignedUserIds"] }, "GetAllAttributeAssignedOptionOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedOptionOutput" } } }, "required": ["status", "data"] }, "AssignOrganizationAttributeOptionToUserInput": { "type": "object", "properties": { "value": { "type": "string" }, "attributeOptionId": { "type": "string" }, "attributeId": { "type": "string" }, "weight": { "type": "number", "minimum": 0, "description": "The weight of the attribute for this user" } }, "required": ["attributeId"] }, "AssignOptionUserOutputData": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the option assigned to the user" }, "memberId": { "type": "number", "description": "The ID form the org membership for the user" }, "attributeOptionId": { "type": "string", "description": "The value of the option" }, "weight": { "type": "number", "nullable": true, "description": "The weight of the attribute for this user" } }, "required": ["id", "memberId", "attributeOptionId"] }, "AssignOptionUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AssignOptionUserOutputData" } }, "required": ["status", "data"] }, "UpdateOrganizationAttributeOptionUserInput": { "type": "object", "properties": { "weight": { "type": "number", "minimum": 0, "description": "The weight of the attribute for this user" } } }, "UpdateOptionUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AssignOptionUserOutputData" } }, "required": ["status", "data"] }, "UnassignOptionUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AssignOptionUserOutputData" } }, "required": ["status", "data"] }, "AttributeAssignmentHistoryActorOutput": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of actor that made the attribute assignment change.", "example": "USER" }, "displayName": { "type": "string", "description": "The human-readable name of the actor that made the change.", "example": "Alice Admin" }, "displayEmail": { "type": "string", "nullable": true, "description": "The email address of the actor when one is available.", "example": "alice@example.com" }, "displayAvatar": { "type": "string", "nullable": true, "description": "The avatar URL of the actor when one is available.", "example": "https://example.com/avatar.png" } }, "required": ["type", "displayName"] }, "AttributeAssignmentHistoryAttributeOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the attribute that changed.", "example": "attr_dept" }, "slug": { "type": "string", "description": "The URL-safe slug of the attribute that changed.", "example": "department" }, "name": { "type": "string", "description": "The display name of the attribute that changed.", "example": "Department" }, "type": { "type": "string", "description": "The attribute input type, such as TEXT, NUMBER, SINGLE_SELECT, or MULTI_SELECT.", "example": "SINGLE_SELECT" } }, "required": ["id", "slug", "name", "type"] }, "AttributeAssignmentHistoryValueOutput": { "type": "object", "properties": { "optionId": { "type": "string", "description": "The unique identifier of the assigned attribute option.", "example": "opt_engineering" }, "optionSlug": { "type": "string", "description": "The URL-safe slug of the assigned attribute option.", "example": "engineering" }, "value": { "type": "string", "description": "The display value of the assigned attribute option.", "example": "Engineering" }, "weight": { "type": "number", "nullable": true, "description": "The routing weight for the assigned option, or null when weights are not used.", "example": 100 } }, "required": ["optionId", "optionSlug", "value"] }, "AttributeAssignmentHistoryChangeOutput": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of assignment change, such as ASSIGNED, UNASSIGNED, VALUE_CHANGED, or WEIGHT_CHANGED.", "example": "VALUE_CHANGED" }, "attribute": { "description": "Details for the attribute affected by this change.", "allOf": [ { "$ref": "#/components/schemas/AttributeAssignmentHistoryAttributeOutput" } ] }, "previous": { "nullable": true, "description": "The previous assignment value before the change, or null when the value was newly assigned.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AttributeAssignmentHistoryValueOutput" } ] }, "current": { "nullable": true, "description": "The current assignment value after the change, or null when the value was unassigned.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AttributeAssignmentHistoryValueOutput" } ] } }, "required": ["type", "attribute"] }, "AttributeAssignmentHistoryLogOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the audit log entry.", "example": "018ff5cd-6dc4-7d57-bcbc-374702ca8b38" }, "timestamp": { "type": "string", "description": "The ISO timestamp when the assignment change was recorded.", "example": "2026-06-04T10:00:00.000Z" }, "source": { "type": "string", "description": "The source that emitted the audit event, such as WEBAPP, API_V2, WEBHOOK, or SYSTEM.", "example": "API_V2" }, "actor": { "description": "Details about the user, app, or system actor that made the change.", "allOf": [ { "$ref": "#/components/schemas/AttributeAssignmentHistoryActorOutput" } ] }, "sourceContext": { "type": "object", "additionalProperties": true, "description": "Source-specific context for the audit event, for example API v2, web app, DSync, or integration sync metadata.", "example": { "kind": "API_V2" } }, "changes": { "description": "The attribute assignment changes captured in this audit log entry.", "type": "array", "items": { "$ref": "#/components/schemas/AttributeAssignmentHistoryChangeOutput" } }, "hasError": { "type": "boolean", "description": "Whether the audit log payload could not be fully parsed.", "example": true } }, "required": ["id", "timestamp", "source", "actor", "sourceContext", "changes"] }, "AttributeAssignmentHistoryDataOutput": { "type": "object", "properties": { "userId": { "type": "number", "description": "The ID of the user whose attribute assignment history was requested.", "example": 5 }, "membershipId": { "type": "number", "description": "The organization membership ID for the requested user.", "example": 42 }, "auditLogs": { "description": "The paginated audit log entries for the user's attribute assignments.", "type": "array", "items": { "$ref": "#/components/schemas/AttributeAssignmentHistoryLogOutput" } }, "nextCursor": { "type": "string", "description": "The cursor to pass to the next request when more audit logs are available.", "example": "018ff5cd-6dc4-7d57-bcbc-374702ca8b38" }, "hasMore": { "type": "boolean", "description": "Whether additional audit log entries are available after this page.", "example": true } }, "required": ["userId", "membershipId", "auditLogs", "hasMore"] }, "GetAttributeAssignmentHistoryOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "description": "The attribute assignment history response payload.", "allOf": [ { "$ref": "#/components/schemas/AttributeAssignmentHistoryDataOutput" } ] } }, "required": ["status", "data"] }, "GetOptionUserOutputData": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the option assigned to the user" }, "attributeId": { "type": "string", "description": "The ID of the attribute" }, "value": { "type": "string", "description": "The value of the option" }, "slug": { "type": "string", "description": "The slug of the option" } }, "required": ["id", "attributeId", "value", "slug"] }, "GetOptionUserOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetOptionUserOutputData" } } }, "required": ["status", "data"] }, "WebhookCustomHeaderOutputDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Authorization" }, "value": { "type": "string", "description": "Always redacted; stored header values are never returned.", "example": "***" } }, "required": ["name", "value"] }, "TeamWebhookOutputDto": { "type": "object", "properties": { "payloadTemplate": { "type": "string", "description": "The template of the payload that will be sent to the subscriberUrl, check cal.com/help/webhooks for more information", "example": "{\"content\":\"A new event has been scheduled\",\"type\":\"{{type}}\",\"name\":\"{{title}}\",\"organizer\":\"{{organizer.name}}\",\"booker\":\"{{attendees.0.name}}\"}" }, "triggers": { "type": "array", "items": { "type": "string", "enum": [ "BOOKING_CREATED", "BOOKING_PAYMENT_INITIATED", "BOOKING_PAID", "BOOKING_RESCHEDULED", "BOOKING_REQUESTED", "BOOKING_CANCELLED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_NO_SHOW_UPDATED", "BOOKING_LOCATION_UPDATED", "BOOKING_TITLE_UPDATED", "BOOKING_REASSIGNED", "BOOKING_SEAT_ACCEPTED", "FORM_SUBMITTED", "MEETING_ENDED", "MEETING_STARTED", "RECORDING_READY", "INSTANT_MEETING", "INSTANT_MEETING_ACCEPTED", "RECORDING_TRANSCRIPTION_GENERATED", "OOO_CREATED", "AFTER_HOSTS_CAL_VIDEO_NO_SHOW", "AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "FORM_SUBMITTED_NO_EVENT", "ROUTING_FORM_FALLBACK_HIT", "DELEGATION_CREDENTIAL_ERROR", "WRONG_ASSIGNMENT_REPORT", "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED", "DELEGATION_CREDENTIAL_ROTATION_REQUIRED", "DELEGATION_CREDENTIAL_SECRET_ROTATED", "CALENDAR_ENTRY_REJECTED", "CAL_EVENT_REGISTRATION_REQUESTED", "CAL_EVENT_REGISTRATION_CONFIRMED", "CAL_EVENT_REGISTRATION_WAITLISTED", "CAL_EVENT_REGISTRATION_DECLINED", "CAL_EVENT_REGISTRATION_CANCELLED" ] } }, "customHeaders": { "description": "Static headers sent on every delivery. Values are always redacted as `\"***\"`.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookCustomHeaderOutputDto" } }, "time": { "type": "number", "description": "How long after the booking start time the no-show triggers are evaluated", "example": 5 }, "timeUnit": { "enum": ["DAY", "HOUR", "MINUTE"], "type": "string", "description": "The unit of the no-show time value", "example": "MINUTE" }, "version": { "enum": ["2021-10-20", "2026-07-27"], "type": "string", "description": "The payload format version of the webhook. Version 2026-07-27 adds generated ICS calendar content (`attendeeIcsContent`, `organizerIcsContent`) to BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_SEAT_ACCEPTED, and BOOKING_PAID (when the payment accepted the booking) payloads. Every version's builder-produced payload carries a `payload.platformOAuthClientId` field naming the owning platform OAuth client (`null` for non-platform events; for the flat-delivered MEETING_STARTED/MEETING_ENDED bodies the field appears at the top level of the body). Zapier deliveries, custom payload templates that do not reference the field, the `AFTER_HOSTS_CAL_VIDEO_NO_SHOW` / `AFTER_GUESTS_CAL_VIDEO_NO_SHOW` bodies (delivered verbatim from the fire-time blob, never built) and the legacy `FORM_SUBMITTED_NO_EVENT` fallback delivery omit it.", "example": "2021-10-20" }, "teamId": { "type": "number" }, "id": { "type": "number" }, "subscriberUrl": { "type": "string" }, "active": { "type": "boolean" }, "secret": { "type": "string" } }, "required": ["payloadTemplate", "triggers", "version", "teamId", "id", "subscriberUrl", "active"] }, "TeamWebhooksOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamWebhookOutputDto" } } }, "required": ["status", "data"] }, "WebhookCustomHeaderInput": { "type": "object", "properties": { "name": { "type": "string", "description": "HTTP header name, at most 256 characters. Names starting with `X-Cal-` are reserved for Cal.com's own headers. Blocked names: host, content-length, transfer-encoding, connection, keep-alive, upgrade, trailer, te, proxy-authorization.", "example": "Authorization" }, "value": { "type": "string", "description": "HTTP header value. Omit (or send the redacted `\"***\"`) on update to keep the stored value, as long as `subscriberUrl` stays the same: stored values are never sent to a new URL. Values are stored encrypted and are always redacted as `\"***\"` on read.", "example": "Bearer crsr_xxxxxxxxxxxxx" } }, "required": ["name"] }, "CreateWebhookInputDto": { "type": "object", "properties": { "payloadTemplate": { "type": "string", "description": "The template of the payload that will be sent to the subscriberUrl, check cal.com/help/webhooks for more information", "example": "{\"content\":\"A new event has been scheduled\",\"type\":\"{{type}}\",\"name\":\"{{title}}\",\"organizer\":\"{{organizer.name}}\",\"booker\":\"{{attendees.0.name}}\"}" }, "active": { "type": "boolean" }, "subscriberUrl": { "type": "string" }, "triggers": { "type": "array", "items": { "type": "string", "enum": [ "BOOKING_CREATED", "BOOKING_PAYMENT_INITIATED", "BOOKING_PAID", "BOOKING_RESCHEDULED", "BOOKING_REQUESTED", "BOOKING_CANCELLED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_NO_SHOW_UPDATED", "BOOKING_LOCATION_UPDATED", "BOOKING_TITLE_UPDATED", "BOOKING_REASSIGNED", "BOOKING_SEAT_ACCEPTED", "FORM_SUBMITTED", "MEETING_ENDED", "MEETING_STARTED", "RECORDING_READY", "INSTANT_MEETING", "INSTANT_MEETING_ACCEPTED", "RECORDING_TRANSCRIPTION_GENERATED", "OOO_CREATED", "AFTER_HOSTS_CAL_VIDEO_NO_SHOW", "AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "FORM_SUBMITTED_NO_EVENT", "ROUTING_FORM_FALLBACK_HIT", "DELEGATION_CREDENTIAL_ERROR", "WRONG_ASSIGNMENT_REPORT", "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED", "DELEGATION_CREDENTIAL_ROTATION_REQUIRED", "DELEGATION_CREDENTIAL_SECRET_ROTATED", "CALENDAR_ENTRY_REJECTED", "CAL_EVENT_REGISTRATION_REQUESTED", "CAL_EVENT_REGISTRATION_CONFIRMED", "CAL_EVENT_REGISTRATION_WAITLISTED", "CAL_EVENT_REGISTRATION_DECLINED", "CAL_EVENT_REGISTRATION_CANCELLED" ] }, "example": [ "BOOKING_CREATED", "BOOKING_RESCHEDULED", "BOOKING_CANCELLED", "BOOKING_CONFIRMED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_COMPLETED", "BOOKING_NO_SHOW", "BOOKING_REOPENED" ] }, "secret": { "type": "string" }, "customHeaders": { "description": "Static HTTP headers sent on every webhook delivery (e.g. Authorization). Max 10 headers, values up to 4 KiB, stored encrypted and redacted on read. Changing `subscriberUrl` drops the stored values unless you send them again. An instance without the webhook header keyring (`CALCOM_KEYRING_WEBHOOK_HEADERS`) answers 400 to any request that sends headers.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookCustomHeaderInput" } }, "version": { "enum": ["2021-10-20", "2026-07-27"], "type": "string", "description": "The payload format version of the webhook. Version 2026-07-27 adds generated ICS calendar content (`attendeeIcsContent`, `organizerIcsContent`) to BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_SEAT_ACCEPTED, and BOOKING_PAID (when the payment accepted the booking) payloads. Every version's builder-produced payload carries a `payload.platformOAuthClientId` field naming the owning platform OAuth client (`null` for non-platform events; for the flat-delivered MEETING_STARTED/MEETING_ENDED bodies the field appears at the top level of the body). Zapier deliveries, custom payload templates that do not reference the field, the `AFTER_HOSTS_CAL_VIDEO_NO_SHOW` / `AFTER_GUESTS_CAL_VIDEO_NO_SHOW` bodies (delivered verbatim from the fire-time blob, never built) and the legacy `FORM_SUBMITTED_NO_EVENT` fallback delivery omit it.", "example": "2021-10-20" }, "time": { "type": "number", "minimum": 1, "description": "How long after the booking start time the no-show triggers are evaluated. Required, together with timeUnit, when subscribing to AFTER_HOSTS_CAL_VIDEO_NO_SHOW or AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "example": 5 }, "timeUnit": { "enum": ["DAY", "HOUR", "MINUTE"], "type": "string", "description": "The unit of the no-show time value", "example": "MINUTE" } }, "required": ["active", "subscriberUrl", "triggers"] }, "TeamWebhookOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamWebhookOutputDto" } }, "required": ["status", "data"] }, "UpdateWebhookInputDto": { "type": "object", "properties": { "payloadTemplate": { "type": "string", "description": "The template of the payload that will be sent to the subscriberUrl, check cal.com/help/webhooks for more information", "example": "{\"content\":\"A new event has been scheduled\",\"type\":\"{{type}}\",\"name\":\"{{title}}\",\"organizer\":\"{{organizer.name}}\",\"booker\":\"{{attendees.0.name}}\"}" }, "active": { "type": "boolean" }, "subscriberUrl": { "type": "string" }, "triggers": { "type": "array", "items": { "type": "string", "enum": [ "BOOKING_CREATED", "BOOKING_PAYMENT_INITIATED", "BOOKING_PAID", "BOOKING_RESCHEDULED", "BOOKING_REQUESTED", "BOOKING_CANCELLED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_NO_SHOW_UPDATED", "BOOKING_LOCATION_UPDATED", "BOOKING_TITLE_UPDATED", "BOOKING_REASSIGNED", "BOOKING_SEAT_ACCEPTED", "FORM_SUBMITTED", "MEETING_ENDED", "MEETING_STARTED", "RECORDING_READY", "INSTANT_MEETING", "INSTANT_MEETING_ACCEPTED", "RECORDING_TRANSCRIPTION_GENERATED", "OOO_CREATED", "AFTER_HOSTS_CAL_VIDEO_NO_SHOW", "AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "FORM_SUBMITTED_NO_EVENT", "ROUTING_FORM_FALLBACK_HIT", "DELEGATION_CREDENTIAL_ERROR", "WRONG_ASSIGNMENT_REPORT", "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED", "DELEGATION_CREDENTIAL_ROTATION_REQUIRED", "DELEGATION_CREDENTIAL_SECRET_ROTATED", "CALENDAR_ENTRY_REJECTED", "CAL_EVENT_REGISTRATION_REQUESTED", "CAL_EVENT_REGISTRATION_CONFIRMED", "CAL_EVENT_REGISTRATION_WAITLISTED", "CAL_EVENT_REGISTRATION_DECLINED", "CAL_EVENT_REGISTRATION_CANCELLED" ] }, "example": [ "BOOKING_CREATED", "BOOKING_RESCHEDULED", "BOOKING_CANCELLED", "BOOKING_CONFIRMED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_COMPLETED", "BOOKING_NO_SHOW", "BOOKING_REOPENED" ] }, "secret": { "type": "string" }, "customHeaders": { "description": "Static HTTP headers sent on every webhook delivery (e.g. Authorization). Max 10 headers, values up to 4 KiB, stored encrypted and redacted on read. Changing `subscriberUrl` drops the stored values unless you send them again. An instance without the webhook header keyring (`CALCOM_KEYRING_WEBHOOK_HEADERS`) answers 400 to any request that sends headers.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookCustomHeaderInput" } }, "version": { "enum": ["2021-10-20", "2026-07-27"], "type": "string", "description": "The payload format version of the webhook. Version 2026-07-27 adds generated ICS calendar content (`attendeeIcsContent`, `organizerIcsContent`) to BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_SEAT_ACCEPTED, and BOOKING_PAID (when the payment accepted the booking) payloads. Every version's builder-produced payload carries a `payload.platformOAuthClientId` field naming the owning platform OAuth client (`null` for non-platform events; for the flat-delivered MEETING_STARTED/MEETING_ENDED bodies the field appears at the top level of the body). Zapier deliveries, custom payload templates that do not reference the field, the `AFTER_HOSTS_CAL_VIDEO_NO_SHOW` / `AFTER_GUESTS_CAL_VIDEO_NO_SHOW` bodies (delivered verbatim from the fire-time blob, never built) and the legacy `FORM_SUBMITTED_NO_EVENT` fallback delivery omit it.", "example": "2021-10-20" }, "time": { "type": "number", "minimum": 1, "description": "How long after the booking start time the no-show triggers are evaluated. Required, together with timeUnit, when subscribing to AFTER_HOSTS_CAL_VIDEO_NO_SHOW or AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "example": 5 }, "timeUnit": { "enum": ["DAY", "HOUR", "MINUTE"], "type": "string", "description": "The unit of the no-show time value", "example": "MINUTE" } } }, "UserOooOutputDto": { "type": "object", "properties": { "userId": { "type": "number", "description": "The ID of the user.", "example": 2 }, "toUserId": { "type": "number", "description": "The ID of the user covering for the out of office period, if applicable.", "example": 2 }, "id": { "type": "number", "description": "The ID of the ooo entry.", "example": 2 }, "uuid": { "type": "string", "description": "The UUID of the ooo entry.", "example": "e84be5a3-4696-49e3-acc7-b2f3999c3b94" }, "start": { "format": "date-time", "type": "string", "description": "The start date and time of the out of office period in ISO 8601 format in UTC timezone.", "example": "2023-05-01T00:00:00.000Z" }, "end": { "format": "date-time", "type": "string", "description": "The end date and time of the out of office period in ISO 8601 format in UTC timezone.", "example": "2023-05-10T23:59:59.999Z" }, "notes": { "type": "string", "description": "Optional notes for the out of office entry.", "example": "Vacation in Hawaii" }, "reason": { "enum": ["unspecified", "vacation", "travel", "sick", "public_holiday"], "type": "string", "description": "the reason for the out of office entry, if applicable", "example": "vacation" } }, "required": ["userId", "id", "uuid", "start", "end"] }, "UserOoosOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserOooOutputDto" } } }, "required": ["status", "data"] }, "CreateOutOfOfficeEntryDto": { "type": "object", "properties": { "start": { "format": "date-time", "type": "string", "description": "The start date and time of the out of office period in ISO 8601 format in UTC timezone.", "example": "2023-05-01T00:00:00.000Z" }, "end": { "format": "date-time", "type": "string", "description": "The end date and time of the out of office period in ISO 8601 format in UTC timezone.", "example": "2023-05-10T23:59:59.999Z" }, "notes": { "type": "string", "description": "Optional notes for the out of office entry.", "example": "Vacation in Hawaii" }, "toUserId": { "type": "number", "description": "The ID of the user covering for the out of office period, if applicable.", "example": 2 }, "reason": { "enum": ["unspecified", "vacation", "travel", "sick", "public_holiday"], "type": "string", "description": "the reason for the out of office entry, if applicable", "example": "vacation" } }, "required": ["start", "end"] }, "UserOooOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UserOooOutputDto" } }, "required": ["status", "data"] }, "UpdateOutOfOfficeEntryDto": { "type": "object", "properties": { "start": { "format": "date-time", "type": "string", "description": "The start date and time of the out of office period in ISO 8601 format in UTC timezone.", "example": "2023-05-01T00:00:00.000Z" }, "end": { "format": "date-time", "type": "string", "description": "The end date and time of the out of office period in ISO 8601 format in UTC timezone.", "example": "2023-05-10T23:59:59.999Z" }, "notes": { "type": "string", "description": "Optional notes for the out of office entry.", "example": "Vacation in Hawaii" }, "toUserId": { "type": "number", "description": "The ID of the user covering for the out of office period, if applicable.", "example": 2 }, "reason": { "enum": ["unspecified", "vacation", "travel", "sick", "public_holiday"], "type": "string", "description": "the reason for the out of office entry, if applicable", "example": "vacation" } } }, "TextWorkflowMessageDto": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the message", "example": "Reminder: Your Meeting {EVENT_NAME} - {EVENT_DATE_ddd, MMM D, YYYY h:mma} with Cal.com" }, "text": { "type": "string", "description": "Text content of the message (used for SMS)", "example": "This is a reminder message from {ORGANIZER} of {EVENT_NAME} to {ATTENDEE} starting here {LOCATION} {MEETING_URL} at {START_TIME_h:mma} {TIMEZONE}." } }, "required": ["subject", "text"] }, "WorkflowPhoneNumberStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_number", "description": "Action to perform, send a text message to a specific phone number", "example": "sms_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto" } ] } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "WorkflowPhoneAttendeeStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_attendee", "description": "Action to perform, send a text message to the phone numbers of the attendees", "example": "sms_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "WorkflowMessageOutputDto": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the message", "example": "Reminder: Your Meeting {EVENT_NAME} - {EVENT_DATE_ddd, MMM D, YYYY h:mma} with Cal.com" }, "html": { "type": "string", "description": "HTML content of the message", "example": "

Reminder for {EVENT_NAME}.

" }, "text": { "type": "string", "description": "Text content of the message (used for SMS/WhatsApp)", "example": "Reminder for {EVENT_NAME}." } }, "required": ["subject"] }, "RoutingFormWorkflowStepOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Intended recipient type", "example": "const", "enum": ["const", "attendee", "email", "phone_number"] }, "email": { "type": "string", "description": "Verified email address if action is EMAIL_ADDRESS", "example": "notifications@example.com" }, "phone": { "type": "string", "description": "Verified Phone if action is SMS_NUMBER or WHATSAPP_NUMBER" }, "phoneRequired": { "type": "boolean", "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true, "default": false }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type used", "example": "reminder" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether a calendar event (.ics) was included (for email actions)", "example": true }, "skipNoShowAttendees": { "type": "boolean", "default": false, "description": "Whether an after-event attendee rating email skips attendees currently marked as no-show.", "example": false }, "sender": { "type": "string", "description": "Displayed sender name used for this step", "example": "Cal.com Notifications" }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/WorkflowMessageOutputDto" } ] }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether auto-translation of the workflow step content for attendees is enabled. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "nullable": true, "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en').", "example": "en" }, "pathId": { "type": "string", "description": "Id of the conditional path this step belongs to; the step only runs when that path's conditions match. Absent for unconditional steps.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "action": { "enum": ["email_attendee", "email_address", "sms_attendee", "sms_number"], "type": "string", "description": "Action to perform", "example": "email_host" } }, "required": ["id", "stepNumber", "recipient", "template", "sender", "message", "action"] }, "WorkflowPathConditionOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the condition", "example": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" }, "field": { "type": "string", "description": "What the condition reads: a booking question identifier, a routing form field id, or an event field id.", "example": "company-size" }, "operator": { "type": "string", "description": "How the field is compared, as the conditions editor stores it. The operator belongs to the field's type: text, email, phone and number fields use `equal`, `not_equal`, `like`, `greater`, `between` and the like; a select uses `select_equals` or `select_any_in`; a multiselect uses `multiselect_equals`. To render an operator with the label the editor shows, resolve the field's type from the booking questions of the event types this workflow is active on, or from the routing form's fields for a form workflow.", "example": "select_equals", "enum": [ "between", "equal", "greater", "greater_or_equal", "is_empty", "is_not_empty", "less", "less_or_equal", "like", "multiselect_equals", "multiselect_not_equals", "not_between", "not_equal", "not_like", "select_any_in", "select_equals", "select_not_any_in", "select_not_equals", "starts_with" ] }, "values": { "description": "The values the field is compared against. Empty for operators that take none, such as is_empty.", "example": ["enterprise"], "type": "array", "items": { "type": "string" } } }, "required": ["id", "field", "operator", "values"] }, "WorkflowStepPathOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the path", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "name": { "type": "string", "description": "Name of the path", "example": "Enterprise leads" }, "position": { "type": "number", "description": "Position of the path among the branches of its step, starting at 0", "example": 0 }, "matches": { "enum": ["all", "any", "none"], "type": "string", "description": "How many of the conditions have to hold for this branch to match — the editor's All, Any and None.", "example": "all" }, "conditions": { "description": "The conditions deciding whether this path matches. A path with no conditions always matches.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionOutputDto" } } }, "required": ["id", "name", "position", "matches", "conditions"] }, "PathsWorkflowStepOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["paths"], "type": "string", "description": "The step that splits the workflow into conditional paths; include this step by id when updating the workflow's steps.", "example": "paths" }, "paths": { "description": "The conditional paths this step splits into, in the order the canvas lays them out", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStepPathOutputDto" } }, "pathId": { "type": "string", "description": "Id of the conditional path this split itself belongs to, when it sits inside a filter's path. Absent at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["id", "stepNumber", "action", "paths"] }, "FilterWorkflowStepOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["filter"], "type": "string", "description": "The step that gates every step after it on a set of conditions; include this step by id when updating the workflow's steps.", "example": "filter" }, "gatedPathId": { "type": "string", "description": "Id of the path this filter gates. Every step carrying this as its pathId runs only when the filter's conditions match.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "matches": { "enum": ["all", "any", "none"], "type": "string", "description": "How many of the conditions have to hold for this gate to pass — the editor's All, Any and None.", "example": "all" }, "conditions": { "description": "The conditions every following step is gated on. A filter with no conditions passes everything.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionOutputDto" } }, "pathId": { "type": "string", "description": "Id of the conditional path this filter itself belongs to, when it sits inside a split branch or another filter. Absent at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["id", "stepNumber", "action", "gatedPathId", "matches", "conditions"] }, "WorkflowDelayDurationOutputDto": { "type": "object", "properties": { "value": { "type": "number", "description": "How long to wait before the next sending step", "example": 2 }, "unit": { "enum": ["hour", "minute", "day"], "type": "string", "description": "Unit for the delay duration", "example": "hour" } }, "required": ["value", "unit"] }, "DelayWorkflowStepOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["delay"], "type": "string", "description": "A wait before the next sending step. Its duration is read-only through the API and can only be edited in the Cal.com app; include this step by id when updating the workflow's steps.", "example": "delay" }, "delay": { "description": "How long this step waits. Absent when the step has no stored duration.", "allOf": [ { "$ref": "#/components/schemas/WorkflowDelayDurationOutputDto" } ] }, "pathId": { "type": "string", "description": "Id of the conditional path this delay belongs to, when it sits inside a split branch or a filter. Absent at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["id", "stepNumber", "action"] }, "LeadEnrichmentWorkflowStepOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["lead_enrichment"], "type": "string", "description": "The step that looks the attendee or form submitter up with the lead enrichment provider when the workflow runs; the steps after it can use the result in their conditions and messages. It can only be added or configured in the Cal.com app; include this step by id when updating the workflow's steps.", "example": "lead_enrichment" }, "pathId": { "type": "string", "description": "Id of the conditional path this step belongs to, when it sits inside a split branch or a filter. Absent at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["id", "stepNumber", "action"] }, "RoutingFormWorkflowActivationOutputDto": { "type": "object", "properties": { "isActiveOnAllRoutingForms": { "type": "boolean", "default": false, "description": "Whether the workflow is active for all routing forms associated with the team/user", "example": false }, "activeOnRoutingFormIds": { "description": "List of Event Type IDs the workflow is specifically active on (if not active on all)", "example": ["5cacdec7-1234-6e1b-78d9-7bcda8a1b332"], "type": "array", "items": { "type": "string" } } } }, "WorkflowTriggerOffsetOutputDto": { "type": "object", "properties": { "value": { "type": "number", "description": "Time value for offset", "example": 24 }, "unit": { "enum": ["hour", "minute", "day"], "type": "string", "description": "Unit for the offset time", "example": "hour" } }, "required": ["value", "unit"] }, "RoutingFormWorkflowTriggerOutputDto": { "type": "object", "properties": { "type": { "enum": ["formSubmitted", "formSubmittedNoEvent"], "type": "string", "description": "Trigger type for the workflow", "example": "formSubmitted" }, "offset": { "description": "Offset details (present for BEFORE_EVENT/AFTER_EVENT/FORM_SUBMITTED_NO_EVENT)", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetOutputDto" } ] } }, "required": ["type"] }, "RoutingFormWorkflowOutput": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the workflow", "example": 101 }, "name": { "type": "string", "description": "Name of the workflow", "example": "Platform Test Workflow" }, "userId": { "type": "number", "description": "ID of the user who owns the workflow (if not team-owned)", "example": 2313 }, "teamId": { "type": "number", "description": "ID of the team owning the workflow", "example": 4214321 }, "createdAt": { "type": "string", "description": "Timestamp of creation", "example": "2024-05-12T10:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Timestamp of last update", "example": "2024-05-12T11:30:00.000Z", "format": "date-time" }, "type": { "enum": ["routing-form"], "type": "string", "description": "type of the workflow", "example": "routing-form", "default": "routing-form" }, "activation": { "description": "Activation settings for the workflow", "allOf": [ { "$ref": "#/components/schemas/RoutingFormWorkflowActivationOutputDto" } ] }, "trigger": { "description": "Trigger configuration", "allOf": [ { "$ref": "#/components/schemas/RoutingFormWorkflowTriggerOutputDto" } ] }, "steps": { "type": "array", "description": "Steps comprising the workflow. A workflow with conditional paths contains one paths step listing its branches, and a filter step for each gate; a workflow with lead enrichment contains one lead enrichment step; steps carrying a pathId only run when that path's conditions match.", "items": { "oneOf": [ { "title": "Step", "$ref": "#/components/schemas/RoutingFormWorkflowStepOutputDto" }, { "title": "Paths step", "$ref": "#/components/schemas/PathsWorkflowStepOutputDto" }, { "title": "Filter step", "$ref": "#/components/schemas/FilterWorkflowStepOutputDto" }, { "title": "Delay step", "$ref": "#/components/schemas/DelayWorkflowStepOutputDto" }, { "title": "Lead enrichment step", "$ref": "#/components/schemas/LeadEnrichmentWorkflowStepOutputDto" } ] } } }, "required": ["id", "name", "type", "activation", "trigger", "steps"] }, "GetRoutingFormWorkflowsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "description": "Indicates the status of the response", "example": "success" }, "data": { "description": "List of workflows", "type": "array", "items": { "$ref": "#/components/schemas/RoutingFormWorkflowOutput" } } }, "required": ["status", "data"] }, "GetRoutingFormWorkflowOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "description": "Indicates the status of the response", "example": "success" }, "data": { "description": "workflow", "type": "array", "items": { "$ref": "#/components/schemas/RoutingFormWorkflowOutput" } } }, "required": ["status", "data"] }, "OnFormSubmittedTriggerDto": { "type": "object", "properties": { "type": { "default": "formSubmitted", "enum": ["formSubmitted"], "type": "string", "description": "Trigger type for the workflow", "example": "formSubmitted" } }, "required": ["type"] }, "WorkflowTriggerOffsetDto": { "type": "object", "properties": { "value": { "type": "number", "minimum": 1, "description": "Time value for offset before/after event trigger", "example": 24 }, "unit": { "enum": ["hour", "minute", "day"], "type": "string", "description": "Unit for the offset time", "example": "hour" } }, "required": ["value", "unit"] }, "OnFormSubmittedNoEventTriggerDto": { "type": "object", "properties": { "offset": { "description": "Offset before/after the trigger time; required for BEFORE_EVENT, AFTER_EVENT, and FORM_SUBMITTED_NO_EVENT", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetDto" } ] }, "type": { "default": "formSubmittedNoEvent", "enum": ["formSubmittedNoEvent"], "type": "string", "description": "Trigger type for the workflow", "example": "formSubmittedNoEvent" } }, "required": ["offset", "type"] }, "HtmlWorkflowMessageDto": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the message", "example": "Reminder: Your Meeting {EVENT_NAME} - {EVENT_DATE_ddd, MMM D, YYYY h:mma} with Cal.com" }, "html": { "type": "string", "description": "HTML content of the message (used for Emails)", "example": "

This is a reminder from {ORGANIZER} of {EVENT_NAME} to {ATTENDEE} starting here {LOCATION} {MEETING_URL} at {START_TIME_h:mma} {TIMEZONE}.

" } }, "required": ["subject", "html"] }, "WorkflowEmailAddressStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_address", "description": "Action to perform, send an email to a specific email address", "example": "email_address" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "verifiedEmailId": { "type": "number", "description": "Email address if recipient is EMAIL, required for action EMAIL_ADDRESS", "example": 31214, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-an-email-for-an-org-team" } }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto" } ] } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "verifiedEmailId", "includeCalendarEvent", "message" ] }, "WorkflowEmailAttendeeStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_attendee", "description": "Action to perform, send an email to the attendees of the event", "example": "email_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "skipNoShowAttendees": { "type": "boolean", "default": false, "description": "Whether an after-event rating email should skip attendees currently marked as no-show. It has no effect for other workflow triggers or templates.", "example": false }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto" } ] } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "RoutingFormWorkflowTriggerDto": { "type": "object", "properties": { "type": { "enum": ["formSubmitted", "formSubmittedNoEvent"], "type": "string", "description": "Trigger type for the routing-form workflow", "example": "formSubmitted" } }, "required": ["type"] }, "WorkflowFormActivationDto": { "type": "object", "properties": { "isActiveOnAllRoutingForms": { "type": "boolean", "description": "Whether the workflow is active for all the routing forms", "example": false }, "activeOnRoutingFormIds": { "description": "List of routing form IDs the workflow applies to", "example": ["abd1-123edf-a213d-123dfwf"], "type": "array", "items": { "type": "number" } } }, "required": ["isActiveOnAllRoutingForms"] }, "CreateFormWorkflowDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the workflow", "example": "Platform Test Workflow" }, "activation": { "description": "Activation settings for the workflow", "allOf": [ { "$ref": "#/components/schemas/WorkflowFormActivationDto" } ] }, "trigger": { "description": "Trigger configuration for the routing-form workflow, allowed triggers are formSubmitted,formSubmittedNoEvent", "oneOf": [ { "title": "Form Submitted", "$ref": "#/components/schemas/OnFormSubmittedTriggerDto" }, { "title": "Form Submitted Without Event", "$ref": "#/components/schemas/OnFormSubmittedNoEventTriggerDto" } ] }, "steps": { "type": "array", "description": "Steps to execute as part of the routing-form workflow, allowed steps are email_attendee,email_address,sms_attendee,sms_number", "items": { "oneOf": [ { "title": "Email Address", "$ref": "#/components/schemas/WorkflowEmailAddressStepDto" }, { "title": "Email Attendee", "$ref": "#/components/schemas/WorkflowEmailAttendeeStepDto" }, { "title": "SMS Attendee", "$ref": "#/components/schemas/WorkflowPhoneAttendeeStepDto" }, { "title": "SMS Number", "$ref": "#/components/schemas/WorkflowPhoneNumberStepDto" } ] } } }, "required": ["name", "activation", "trigger", "steps"] }, "UpdateDelayWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": ["delay"], "type": "string", "description": "Marks an existing delay step. Delays can only be created or edited in the Cal.com app. When updating steps, include this step as { action: \"delay\", id } using the id returned by GET so the wait is preserved. Its position is fixed, so it takes no stepNumber: an update that moves another step to the other side of it, or reuses the stepNumber GET returned for it, is rejected.", "example": "delay" }, "id": { "type": "number", "description": "Unique identifier of the existing delay step. A delay step cannot be created through the API, so the id is required.", "example": 67244 } }, "required": ["action", "id"] }, "UpdateEmailAddressWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_address", "description": "Action to perform, send an email to a specific email address", "example": "email_address" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "verifiedEmailId": { "type": "number", "description": "Email address if recipient is EMAIL, required for action EMAIL_ADDRESS", "example": 31214, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-an-email-for-an-org-team" } }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "verifiedEmailId", "includeCalendarEvent", "message" ] }, "UpdateEmailAttendeeWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_attendee", "description": "Action to perform, send an email to the attendees of the event", "example": "email_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "skipNoShowAttendees": { "type": "boolean", "default": false, "description": "Whether an after-event rating email should skip attendees currently marked as no-show. It has no effect for other workflow triggers or templates.", "example": false }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "UpdateEmailHostWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_host", "description": "Action to perform, send an email to the host of the event", "example": "email_host" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "UpdateFilterWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": ["filter"], "type": "string", "description": "Marks the step that gates everything after it on a set of conditions. Those conditions can only be edited in the Cal.com app. When updating steps, include this step as { action: \"filter\", id } using the id returned by GET so the gate is preserved. Its position relative to the steps it gates is fixed, so it takes no stepNumber.", "example": "filter" }, "id": { "type": "number", "description": "Unique identifier of the existing filter step. A filter step cannot be created through the API, so the id is required.", "example": 67244 } }, "required": ["action", "id"] }, "UpdateLeadEnrichmentWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": ["lead_enrichment"], "type": "string", "description": "Marks the step that looks the attendee or form submitter up with the lead enrichment provider before the steps after it run. It can only be added or configured in the Cal.com app. When updating steps, include this step as { action: \"lead_enrichment\", id } using the id returned by GET so the lookup is preserved. Its position is fixed, so it takes no stepNumber: an update that moves another step to the other side of it, or reuses the stepNumber GET returned for it, is rejected.", "example": "lead_enrichment" }, "id": { "type": "number", "description": "Unique identifier of the existing lead enrichment step. A lead enrichment step cannot be created through the API, so the id is required.", "example": 67244 } }, "required": ["action", "id"] }, "UpdatePathsWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": ["paths"], "type": "string", "description": "Marks the step that splits the workflow into conditional paths. Paths and their conditions can only be edited in the Cal.com app. When updating steps, include this step as { action: \"paths\", id } using the id returned by GET so the split is preserved. It is always placed after every step outside a path, followed by the steps inside its paths, so it takes no stepNumber.", "example": "paths" }, "id": { "type": "number", "description": "Unique identifier of the existing paths step. A paths step cannot be created through the API, so the id is required.", "example": 67244 } }, "required": ["action", "id"] }, "UpdatePhoneAttendeeWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_attendee", "description": "Action to perform, send a text message to the phone numbers of the attendees", "example": "sms_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "UpdatePhoneWhatsAppNumberWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "whatsapp_number", "description": "Action to perform, send a text message via whatsapp to a specific phone number", "example": "whatsapp_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "UpdateWhatsAppAttendeePhoneWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "whatsapp_attendee", "description": "Action to perform", "example": "whatsapp_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "message": { "description": "Message content for this step, send a text message via whatsapp to the phone numbers of the attendees", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "UpdatePhoneNumberWorkflowStepDto": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_number", "description": "Action to perform, send a text message to a specific phone number", "example": "sms_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "UpdateFormWorkflowDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the workflow", "example": "Rounting-form Test Workflow" }, "trigger": { "description": "Trigger configuration for the routing-form workflow, allowed triggers are formSubmitted,formSubmittedNoEvent", "oneOf": [ { "title": "Form Submitted", "$ref": "#/components/schemas/OnFormSubmittedTriggerDto" }, { "title": "Form Submitted Without Event", "$ref": "#/components/schemas/OnFormSubmittedNoEventTriggerDto" } ] }, "steps": { "type": "array", "minItems": 1, "description": "Steps to execute as part of the routing-form workflow, allowed steps are email_attendee,email_address,sms_attendee,sms_number. If the workflow has conditional paths, delays or lead enrichment, the array must also include its existing \"paths\", \"filter\", \"delay\" and \"lead_enrichment\" steps and every step that belongs to a path, using the ids returned by GET — paths, filters, delays and lead enrichment can only be edited in the Cal.com app.", "items": { "oneOf": [ { "title": "Email Address", "$ref": "#/components/schemas/UpdateEmailAddressWorkflowStepDto" }, { "title": "Email Attendee", "$ref": "#/components/schemas/UpdateEmailAttendeeWorkflowStepDto" }, { "title": "SMS Attendee", "$ref": "#/components/schemas/UpdatePhoneAttendeeWorkflowStepDto" }, { "title": "SMS Number", "$ref": "#/components/schemas/UpdatePhoneNumberWorkflowStepDto" }, { "title": "Paths (existing step)", "$ref": "#/components/schemas/UpdatePathsWorkflowStepDto" }, { "title": "Filter (existing step)", "$ref": "#/components/schemas/UpdateFilterWorkflowStepDto" }, { "title": "Delay (existing step)", "$ref": "#/components/schemas/UpdateDelayWorkflowStepDto" }, { "title": "Lead enrichment (existing step)", "$ref": "#/components/schemas/UpdateLeadEnrichmentWorkflowStepDto" } ] } }, "activation": { "$ref": "#/components/schemas/WorkflowFormActivationDto" } } }, "EventTypeWorkflowStepOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Intended recipient type", "example": "const", "enum": ["const", "attendee", "email", "phone_number"] }, "email": { "type": "string", "description": "Verified email address if action is EMAIL_ADDRESS", "example": "notifications@example.com" }, "phone": { "type": "string", "description": "Verified Phone if action is SMS_NUMBER or WHATSAPP_NUMBER" }, "phoneRequired": { "type": "boolean", "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true, "default": false }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type used", "example": "reminder" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether a calendar event (.ics) was included (for email actions)", "example": true }, "skipNoShowAttendees": { "type": "boolean", "default": false, "description": "Whether an after-event attendee rating email skips attendees currently marked as no-show.", "example": false }, "sender": { "type": "string", "description": "Displayed sender name used for this step", "example": "Cal.com Notifications" }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/WorkflowMessageOutputDto" } ] }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether auto-translation of the workflow step content for attendees is enabled. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "nullable": true, "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en').", "example": "en" }, "pathId": { "type": "string", "description": "Id of the conditional path this step belongs to; the step only runs when that path's conditions match. Absent for unconditional steps.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "description": "Action to perform", "example": "email_host" } }, "required": ["id", "stepNumber", "recipient", "template", "sender", "message", "action"] }, "WorkflowStepPathOutputDto_2026_09_22": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the path", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "name": { "type": "string", "description": "Name of the path", "example": "Enterprise leads" }, "position": { "type": "number", "description": "Position of the path among the branches of its step, starting at 0", "example": 0 }, "conditions": { "description": "The conditions deciding whether this path matches. A path with no conditions always matches.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionOutputDto" } }, "matches": { "enum": ["all", "any", "none", "not_all"], "type": "string", "description": "all: every condition matches; any: at least one matches; none: no conditions match; not_all: at least one condition does not match.", "example": "all" } }, "required": ["id", "name", "position", "conditions", "matches"] }, "PathsWorkflowStepOutputDto_2026_09_22": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["paths"], "type": "string", "description": "The step that splits the workflow into conditional paths; include this step by id when updating the workflow's steps.", "example": "paths" }, "pathId": { "type": "string", "description": "Id of the conditional path this split itself belongs to, when it sits inside a filter's path. Absent at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStepPathOutputDto_2026_09_22" } } }, "required": ["id", "stepNumber", "action", "paths"] }, "FilterWorkflowStepOutputDto_2026_09_22": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the step", "example": 67244 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["filter"], "type": "string", "description": "The step that gates every step after it on a set of conditions; include this step by id when updating the workflow's steps.", "example": "filter" }, "gatedPathId": { "type": "string", "description": "Id of the path this filter gates. Every step carrying this as its pathId runs only when the filter's conditions match.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "conditions": { "description": "The conditions every following step is gated on. A filter with no conditions passes everything.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionOutputDto" } }, "pathId": { "type": "string", "description": "Id of the conditional path this filter itself belongs to, when it sits inside a split branch or another filter. Absent at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" }, "matches": { "enum": ["all", "any", "none", "not_all"], "type": "string", "description": "all: every condition matches; any: at least one matches; none: no conditions match; not_all: at least one condition does not match.", "example": "all" } }, "required": ["id", "stepNumber", "action", "gatedPathId", "conditions", "matches"] }, "WebhookWorkflowStepOutputDto_2026_09_22": { "type": "object", "properties": { "id": { "type": "number", "description": "Workflow step id", "example": 123 }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "action": { "enum": ["webhook"], "type": "string", "description": "Action to perform", "example": "webhook" }, "url": { "type": "string", "description": "The HTTP or HTTPS URL that receives signed booking payloads." }, "hasSecret": { "type": "boolean", "description": "Whether a signing secret is saved. The secret itself is never returned." }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" } }, "required": ["id", "stepNumber", "action", "url", "hasSecret"] }, "EventTypeWorkflowActivationOutputDto": { "type": "object", "properties": { "isActiveOnAllEventTypes": { "type": "boolean", "default": false, "description": "Whether the workflow is active for all event types associated with the team/user", "example": false }, "activeOnEventTypeIds": { "description": "List of Event Type IDs the workflow is specifically active on (if not active on all)", "example": [698191, 698192], "type": "array", "items": { "type": "number" } } } }, "EventTypeWorkflowTriggerOutputDto": { "type": "object", "properties": { "type": { "enum": [ "beforeEvent", "eventCancelled", "newEvent", "afterEvent", "rescheduleEvent", "afterHostsCalVideoNoShow", "afterGuestsCalVideoNoShow", "bookingRejected", "bookingRequested", "bookingPaymentInitiated", "bookingPaid", "bookingNoShowUpdated" ], "type": "string", "description": "Trigger type for the workflow", "example": "beforeEvent" }, "offset": { "description": "Offset details (present for BEFORE_EVENT/AFTER_EVENT)", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetOutputDto" } ] } }, "required": ["type"] }, "EventTypeWorkflowOutput_2026_09_22": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the workflow", "example": 101 }, "name": { "type": "string", "description": "Name of the workflow", "example": "Platform Test Workflow" }, "userId": { "type": "number", "description": "ID of the user who owns the workflow (if not team-owned)", "example": 2313 }, "teamId": { "type": "number", "description": "ID of the team owning the workflow", "example": 4214321 }, "createdAt": { "type": "string", "description": "Timestamp of creation", "example": "2024-05-12T10:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Timestamp of last update", "example": "2024-05-12T11:30:00.000Z", "format": "date-time" }, "type": { "enum": ["event-type"], "type": "string", "description": "type of the workflow", "example": "event-type", "default": "event-type" }, "activation": { "description": "Activation settings for the workflow", "allOf": [ { "$ref": "#/components/schemas/EventTypeWorkflowActivationOutputDto" } ] }, "trigger": { "description": "Trigger configuration", "allOf": [ { "$ref": "#/components/schemas/EventTypeWorkflowTriggerOutputDto" } ] }, "steps": { "type": "array", "items": { "oneOf": [ { "title": "Step", "$ref": "#/components/schemas/EventTypeWorkflowStepOutputDto" }, { "title": "Paths step", "$ref": "#/components/schemas/PathsWorkflowStepOutputDto_2026_09_22" }, { "title": "Filter step", "$ref": "#/components/schemas/FilterWorkflowStepOutputDto_2026_09_22" }, { "title": "Delay step", "$ref": "#/components/schemas/DelayWorkflowStepOutputDto" }, { "title": "Lead enrichment step", "$ref": "#/components/schemas/LeadEnrichmentWorkflowStepOutputDto" }, { "title": "Webhook step", "$ref": "#/components/schemas/WebhookWorkflowStepOutputDto_2026_09_22" } ] } } }, "required": ["id", "name", "type", "activation", "trigger", "steps"] }, "GetEventTypeWorkflowsOutput_2026_09_22": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "description": "Indicates the status of the response", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeWorkflowOutput_2026_09_22" } } }, "required": ["status", "data"] }, "GetEventTypeWorkflowOutput_2026_09_22": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "description": "Indicates the status of the response", "example": "success" }, "data": { "$ref": "#/components/schemas/EventTypeWorkflowOutput_2026_09_22" } }, "required": ["status", "data"] }, "WorkflowConditionOperatorOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The value to send as a condition's `operator`", "example": "select_equals" }, "label": { "type": "string", "description": "How the comparison reads in the editor. Ids differ by field type where the label does not — `equal` on a text field and `select_equals` on a select both read \"Equals\" — so render this rather than the id.", "example": "Equals" } }, "required": ["id", "label"] }, "WorkflowConditionFieldOptionOutputDto": { "type": "object", "properties": { "value": { "type": "string", "description": "The value a condition compares against", "example": "enterprise" }, "label": { "type": "string", "description": "How the option reads in the editor", "example": "Enterprise" } }, "required": ["value", "label"] }, "WorkflowConditionFieldOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The value to send as a condition's `field`", "example": "company-size" }, "label": { "type": "string", "description": "How the field reads in the editor", "example": "Company size" }, "type": { "type": "string", "description": "What kind of answer the field holds, which decides the operators it accepts", "example": "select" }, "operators": { "description": "The comparisons this field accepts", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowConditionOperatorOutputDto" } }, "options": { "description": "The values this field can hold, for select and multiselect fields. Empty for the rest.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowConditionFieldOptionOutputDto" } }, "missingFrom": { "description": "Names of the event types this workflow is active on that do not ask for this field. A condition on it is scored false for them, so the branch never runs for those triggers.", "example": ["Intro call"], "type": "array", "items": { "type": "string" } }, "hasTypeConflict": { "type": "boolean", "description": "Whether the entities this workflow is active on disagree about the field's type. The operators listed are those of the first definition, and a condition may behave differently per trigger.", "example": false } }, "required": ["id", "label", "type", "operators", "options", "missingFrom", "hasTypeConflict"] }, "WorkflowConditionFieldsDataOutputDto": { "type": "object", "properties": { "truncated": { "type": "boolean", "description": "True when the catalog samples the first 100 active entities. Warnings cover only that sample." }, "fields": { "description": "The fields a condition on this workflow can read", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowConditionFieldOutputDto" } }, "activeOn": { "description": "The event types the catalog was built from — what the workflow is active on, capped at 100.", "example": ["Intro call", "Demo"], "type": "array", "items": { "type": "string" } }, "isActiveOnAll": { "type": "boolean", "description": "Present when the workflow is active on everything its owner has, in which case `activeOn` lists what the cap allowed.", "example": true } }, "required": ["truncated", "fields", "activeOn"] }, "WorkflowConditionFieldsOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/WorkflowConditionFieldsDataOutputDto" } }, "required": ["status", "data"] }, "WorkflowPathConditionInputDto_2026_09_22": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[\\w-]{1,64}$", "description": "Identifier of the condition. Generated when omitted; send the id from GET to edit one.", "example": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" }, "field": { "type": "string", "maxLength": 255, "description": "The booking question or event field this condition reads. Use a field identifier returned by the workflow condition-fields endpoint.", "example": "company-size" }, "operator": { "type": "string", "maxLength": 64, "description": "How the field is compared. The operator has to be one the field's type accepts — `equal` for a text or number field, `select_equals` for a select, `multiselect_equals` for a multiselect — because a condition whose operator its field rejects is scored false and silences the branch.", "example": "select_equals", "enum": [ "between", "equal", "greater", "greater_or_equal", "is_empty", "is_not_empty", "less", "less_or_equal", "like", "multiselect_equals", "multiselect_not_equals", "not_between", "not_equal", "not_like", "select_any_in", "select_equals", "select_not_any_in", "select_not_equals", "starts_with" ] }, "values": { "maxItems": 100, "description": "The values the field is compared against. Omit or send an empty list for operators that take none, such as is_empty.", "example": ["enterprise"], "default": [], "type": "array", "items": { "type": "string", "maxLength": 1000 } } }, "required": ["field", "operator"] }, "WorkflowPathInputDto_2026_09_22": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the path. Generated when omitted; send the id from GET to edit an existing branch rather than replace it. An existing path id must belong to this workflow and this gate.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "name": { "type": "string", "maxLength": 255, "description": "Name of the branch, shown on the canvas", "example": "Enterprise leads" }, "matches": { "enum": ["all", "any", "none", "not_all"], "type": "string", "description": "How conditions must match: all (every condition), any (at least one), none (no conditions), or not_all (at least one condition does not match). Omit to preserve an existing branch’s mode; new branches default to all.", "example": "all", "default": "all" }, "conditions": { "description": "The conditions deciding whether this branch matches. Omit or send an empty list for a branch that always matches.", "default": [], "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionInputDto_2026_09_22" } } }, "required": ["name"] }, "CreatePathsWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["paths"], "type": "string", "description": "Marks the step that splits the workflow into conditional paths. It is always placed after every step outside a path, followed by the steps inside its paths, so it takes no stepNumber. Send `paths` to author the split and omit this step to delete it.", "example": "paths" }, "paths": { "minItems": 2, "description": "The branches this step splits into, in the order they should appear on the canvas. A split needs at least two. Omit to leave the persisted branches untouched.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathInputDto_2026_09_22" } }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the filter path this split itself sits inside. Omit it for a split at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["action"] }, "CreateFilterWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["filter"], "type": "string", "description": "Marks the step that gates everything after it on a set of conditions. Its position relative to the steps it gates is fixed, so it takes no stepNumber. Send `conditions` to author the gate and omit this step to delete it.", "example": "filter" }, "gatedPathId": { "type": "string", "format": "uuid", "description": "Id of the path this filter gates, so steps can name it as their pathId. Generated when omitted; send the gatedPathId from GET to keep the steps already behind this gate.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "matches": { "enum": ["all", "any", "none", "not_all"], "type": "string", "description": "all: every condition matches; any: at least one matches; none: no conditions match; not_all: at least one condition does not match.", "example": "all", "default": "all" }, "conditions": { "description": "The conditions every following step is gated on. Omit to leave the persisted conditions untouched; send an empty list for a gate that passes everything.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionInputDto_2026_09_22" } }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this filter itself sits inside. Omit it for a filter at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["action"] }, "OnBeforeEventTriggerDto": { "type": "object", "properties": { "offset": { "description": "Offset before/after the trigger time; required for BEFORE_EVENT, AFTER_EVENT, and FORM_SUBMITTED_NO_EVENT", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetDto" } ] }, "type": { "default": "beforeEvent", "enum": ["beforeEvent"], "type": "string", "description": "Trigger type for the workflow", "example": "beforeEvent" } }, "required": ["offset", "type"] }, "OnAfterEventTriggerDto": { "type": "object", "properties": { "offset": { "description": "Offset before/after the trigger time; required for BEFORE_EVENT, AFTER_EVENT, and FORM_SUBMITTED_NO_EVENT", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetDto" } ] }, "type": { "default": "afterEvent", "enum": ["afterEvent"], "type": "string", "description": "Trigger type for the workflow", "example": "afterEvent" } }, "required": ["offset", "type"] }, "OnCancelTriggerDto": { "type": "object", "properties": { "type": { "default": "eventCancelled", "enum": ["eventCancelled"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnCreationTriggerDto": { "type": "object", "properties": { "type": { "default": "newEvent", "enum": ["newEvent"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnRescheduleTriggerDto": { "type": "object", "properties": { "type": { "default": "rescheduleEvent", "enum": ["rescheduleEvent"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnNoShowUpdateTriggerDto": { "type": "object", "properties": { "type": { "default": "bookingNoShowUpdated", "enum": ["bookingNoShowUpdated"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnRejectedTriggerDto": { "type": "object", "properties": { "type": { "default": "bookingRejected", "enum": ["bookingRejected"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnRequestedTriggerDto": { "type": "object", "properties": { "type": { "default": "bookingRequested", "enum": ["bookingRequested"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnPaymentInitiatedTriggerDto": { "type": "object", "properties": { "type": { "default": "bookingPaymentInitiated", "enum": ["bookingPaymentInitiated"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnPaidTriggerDto": { "type": "object", "properties": { "type": { "default": "bookingPaid", "enum": ["bookingPaid"], "type": "string", "description": "Trigger type for the workflow" } }, "required": ["type"] }, "OnAfterCalVideoGuestsNoShowTriggerDto": { "type": "object", "properties": { "offset": { "description": "Offset before/after the trigger time; required for BEFORE_EVENT, AFTER_EVENT, and FORM_SUBMITTED_NO_EVENT", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetDto" } ] }, "type": { "default": "afterGuestsCalVideoNoShow", "enum": ["afterGuestsCalVideoNoShow"], "type": "string", "description": "Trigger type for the workflow", "example": "afterGuestsCalVideoNoShow" } }, "required": ["offset", "type"] }, "OnAfterCalVideoHostsNoShowTriggerDto": { "type": "object", "properties": { "offset": { "description": "Offset before/after the trigger time; required for BEFORE_EVENT, AFTER_EVENT, and FORM_SUBMITTED_NO_EVENT", "allOf": [ { "$ref": "#/components/schemas/WorkflowTriggerOffsetDto" } ] }, "type": { "default": "afterHostsCalVideoNoShow", "enum": ["afterHostsCalVideoNoShow"], "type": "string", "description": "Trigger type for the workflow", "example": "afterHostsCalVideoNoShow" } }, "required": ["offset", "type"] }, "HtmlWorkflowMessageDto_2026_09_22": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the message", "example": "Reminder: Your Meeting {EVENT_NAME} - {EVENT_DATE_ddd, MMM D, YYYY h:mma} with Cal.com" }, "html": { "type": "string", "description": "HTML content of the message (used for Emails)", "example": "

This is a reminder from {ORGANIZER} of {EVENT_NAME} to {ATTENDEE} starting here {LOCATION} {MEETING_URL} at {START_TIME_h:mma} {TIMEZONE}.

" } }, "required": ["subject", "html"] }, "WorkflowEmailAddressStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_address", "description": "Action to perform, send an email to a specific email address", "example": "email_address" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "verifiedEmailId": { "type": "number", "description": "Email address if recipient is EMAIL, required for action EMAIL_ADDRESS", "example": 31214, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-an-email-for-an-org-team" } }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto_2026_09_22" } ] } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "verifiedEmailId", "includeCalendarEvent", "message" ] }, "WorkflowEmailAttendeeStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_attendee", "description": "Action to perform, send an email to the attendees of the event", "example": "email_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "skipNoShowAttendees": { "type": "boolean", "default": false, "description": "Whether an after-event rating email should skip attendees currently marked as no-show. It has no effect for other workflow triggers or templates.", "example": false }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto_2026_09_22" } ] } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "WorkflowEmailHostStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_host", "description": "Action to perform, send an email to the host of the event", "example": "email_host" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto_2026_09_22" } ] } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "TextWorkflowMessageDto_2026_09_22": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the message", "example": "Reminder: Your Meeting {EVENT_NAME} - {EVENT_DATE_ddd, MMM D, YYYY h:mma} with Cal.com" }, "text": { "type": "string", "description": "Text content of the message (used for SMS)", "example": "This is a reminder message from {ORGANIZER} of {EVENT_NAME} to {ATTENDEE} starting here {LOCATION} {MEETING_URL} at {START_TIME_h:mma} {TIMEZONE}." } }, "required": ["subject", "text"] }, "WorkflowPhoneWhatsAppAttendeeStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "whatsapp_attendee", "description": "Action to perform", "example": "whatsapp_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "message": { "description": "Message content for this step, send a text message via whatsapp to the phone numbers of the attendees", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "WorkflowPhoneWhatsAppNumberStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "whatsapp_number", "description": "Action to perform, send a text message via whatsapp to a specific phone number", "example": "whatsapp_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "WorkflowPhoneNumberStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_number", "description": "Action to perform, send a text message to a specific phone number", "example": "sms_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "WorkflowPhoneAttendeeStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_attendee", "description": "Action to perform, send a text message to the phone numbers of the attendees", "example": "sms_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "WorkflowWebhookStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["webhook"], "type": "string", "description": "Action to perform", "example": "webhook" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The HTTP or HTTPS URL that receives signed booking payloads.", "example": "https://example.com/webhook" }, "secret": { "type": "string", "minLength": 1, "maxLength": 255, "description": "HMAC key for X-Cal-Signature-256. This secret is write-only and is never returned.", "writeOnly": true }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" } }, "required": ["action", "stepNumber", "url"] }, "EventTypeWorkflowTriggerDto": { "type": "object", "properties": { "type": { "enum": [ "beforeEvent", "eventCancelled", "newEvent", "afterEvent", "rescheduleEvent", "afterHostsCalVideoNoShow", "afterGuestsCalVideoNoShow", "bookingRejected", "bookingRequested", "bookingPaymentInitiated", "bookingPaid", "bookingNoShowUpdated" ], "type": "string", "description": "Trigger type for the event-type workflow", "example": "beforeEvent" } }, "required": ["type"] }, "WorkflowActivationDto_2026_09_22": { "type": "object", "properties": { "isActiveOnAllEventTypes": { "type": "boolean", "default": false, "description": "Whether the workflow is active for all the event-types", "example": false }, "activeOnEventTypeIds": { "default": [], "description": "List of event-types IDs the workflow applies to, required if isActiveOnAllEventTypes is false", "example": [698191], "type": "array", "items": { "type": "number" } } }, "required": ["isActiveOnAllEventTypes"] }, "CreateEventTypeWorkflowDto_2026_09_22": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the workflow", "example": "Platform Test Workflow" }, "activation": { "description": "Activation settings for the workflow", "allOf": [ { "$ref": "#/components/schemas/WorkflowActivationDto_2026_09_22" } ] }, "trigger": { "description": "Trigger configuration for the event-type workflow, allowed triggers are beforeEvent,eventCancelled,newEvent,afterEvent,rescheduleEvent,afterHostsCalVideoNoShow,afterGuestsCalVideoNoShow,bookingRejected,bookingRequested,bookingPaymentInitiated,bookingPaid,bookingNoShowUpdated", "oneOf": [ { "title": "Before Event", "$ref": "#/components/schemas/OnBeforeEventTriggerDto" }, { "title": "After Event", "$ref": "#/components/schemas/OnAfterEventTriggerDto" }, { "title": "Event Cancelled", "$ref": "#/components/schemas/OnCancelTriggerDto" }, { "title": "New Event", "$ref": "#/components/schemas/OnCreationTriggerDto" }, { "title": "Event Rescheduled", "$ref": "#/components/schemas/OnRescheduleTriggerDto" }, { "title": "After Guest No-Show", "$ref": "#/components/schemas/OnAfterCalVideoGuestsNoShowTriggerDto" }, { "title": "After Host No-Show", "$ref": "#/components/schemas/OnAfterCalVideoHostsNoShowTriggerDto" }, { "title": "Booking Rejected", "$ref": "#/components/schemas/OnRejectedTriggerDto" }, { "title": "Booking Requested", "$ref": "#/components/schemas/OnRequestedTriggerDto" }, { "title": "Booking Paid", "$ref": "#/components/schemas/OnPaidTriggerDto" }, { "title": "Booking Payment Initiated", "$ref": "#/components/schemas/OnPaymentInitiatedTriggerDto" }, { "title": "Booking No-Show Updated", "$ref": "#/components/schemas/OnNoShowUpdateTriggerDto" } ] }, "steps": { "type": "array", "minItems": 1, "description": "Steps to execute as part of the event-type workflow, allowed steps are email_host,email_attendee,email_address,sms_attendee,sms_number,whatsapp_attendee,whatsapp_number,cal_ai_phone_call,paths,filter", "items": { "oneOf": [ { "title": "Paths", "$ref": "#/components/schemas/CreatePathsWorkflowStepDto_2026_09_22" }, { "title": "Filter", "$ref": "#/components/schemas/CreateFilterWorkflowStepDto_2026_09_22" }, { "title": "Email Address", "$ref": "#/components/schemas/WorkflowEmailAddressStepDto_2026_09_22" }, { "title": "Email Attendee", "$ref": "#/components/schemas/WorkflowEmailAttendeeStepDto_2026_09_22" }, { "title": "Email Host", "$ref": "#/components/schemas/WorkflowEmailHostStepDto_2026_09_22" }, { "title": "WhatsApp Attendee", "$ref": "#/components/schemas/WorkflowPhoneWhatsAppAttendeeStepDto_2026_09_22" }, { "title": "WhatsApp Number", "$ref": "#/components/schemas/WorkflowPhoneWhatsAppNumberStepDto_2026_09_22" }, { "title": "SMS Number", "$ref": "#/components/schemas/WorkflowPhoneNumberStepDto_2026_09_22" }, { "title": "SMS Attendee", "$ref": "#/components/schemas/WorkflowPhoneAttendeeStepDto_2026_09_22" }, { "title": "Webhook", "$ref": "#/components/schemas/WorkflowWebhookStepDto_2026_09_22" } ] } } }, "required": ["name", "activation", "trigger", "steps"] }, "UpdateEmailAddressWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_address", "description": "Action to perform, send an email to a specific email address", "example": "email_address" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "verifiedEmailId": { "type": "number", "description": "Email address if recipient is EMAIL, required for action EMAIL_ADDRESS", "example": 31214, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-an-email-for-an-org-team" } }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto_2026_09_22" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "verifiedEmailId", "includeCalendarEvent", "message" ] }, "UpdateEmailAttendeeWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_attendee", "description": "Action to perform, send an email to the attendees of the event", "example": "email_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "skipNoShowAttendees": { "type": "boolean", "default": false, "description": "Whether an after-event rating email should skip attendees currently marked as no-show. It has no effect for other workflow triggers or templates.", "example": false }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto_2026_09_22" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "UpdateEmailHostWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "email_host", "description": "Action to perform, send an email to the host of the event", "example": "email_host" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "includeCalendarEvent": { "type": "boolean", "default": false, "description": "Whether to include a calendar event in the notification, can be included with actions email_host, email_attendee, email_address", "example": true }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/HtmlWorkflowMessageDto_2026_09_22" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": [ "action", "stepNumber", "recipient", "template", "sender", "includeCalendarEvent", "message" ] }, "UpdateFilterWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["filter"], "type": "string", "description": "Marks the step that gates everything after it on a set of conditions. Its position relative to the steps it gates is fixed, so it takes no stepNumber. Send `conditions` to author the gate and omit this step to delete it.", "example": "filter" }, "id": { "type": "number", "description": "Unique identifier of an existing filter step, from GET. Omit it to create the gate.", "example": 67244 }, "gatedPathId": { "type": "string", "format": "uuid", "description": "Id of the path this filter gates, so steps can name it as their pathId. Generated when omitted; send the gatedPathId from GET to keep the steps already behind this gate.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "matches": { "enum": ["all", "any", "none", "not_all"], "type": "string", "description": "all: every condition matches; any: at least one matches; none: no conditions match; not_all: at least one condition does not match.", "example": "all", "default": "all" }, "conditions": { "description": "The conditions every following step is gated on. Omit to leave the persisted conditions untouched; send an empty list for a gate that passes everything.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathConditionInputDto_2026_09_22" } }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this filter itself sits inside. Omit it for a filter at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["action"] }, "UpdatePathsWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["paths"], "type": "string", "description": "Marks the step that splits the workflow into conditional paths. It is always placed after every step outside a path, followed by the steps inside its paths, so it takes no stepNumber. Send `paths` to author the split and omit this step to delete it.", "example": "paths" }, "id": { "type": "number", "description": "Unique identifier of an existing paths step, from GET. Omit it to create the split.", "example": 67244 }, "paths": { "minItems": 2, "description": "The branches this step splits into, in the order they should appear on the canvas. A split needs at least two. Omit to leave the persisted branches untouched.", "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPathInputDto_2026_09_22" } }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the filter path this split itself sits inside. Omit it for a split at the top level.", "example": "8b2f0c31-4a6d-4f89-b1c5-6d0e8a4f2b73" } }, "required": ["action"] }, "UpdateDelayWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["delay"], "type": "string", "description": "Marks an existing delay step. Delays can only be created or edited in the Cal.com app. When updating steps, include this step as { action: \"delay\", id } using the id returned by GET so the wait is preserved. Its position is fixed, so it takes no stepNumber: an update that moves another step to the other side of it, or reuses the stepNumber GET returned for it, is rejected.", "example": "delay" }, "id": { "type": "number", "description": "Unique identifier of the existing delay step. A delay step cannot be created through the API, so the id is required.", "example": 67244 } }, "required": ["action", "id"] }, "UpdateLeadEnrichmentWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["lead_enrichment"], "type": "string", "description": "Marks the step that looks the attendee up with the lead enrichment provider before the steps after it run. It can only be added or configured in the Cal.com app. When updating steps, include this step as { action: \"lead_enrichment\", id } using the id returned by GET so the lookup is preserved. Its position is fixed, so it takes no stepNumber: an update that moves another step to the other side of it, or reuses the stepNumber GET returned for it, is rejected.", "example": "lead_enrichment" }, "id": { "type": "number", "description": "Unique identifier of the existing lead enrichment step. A lead enrichment step cannot be created through the API, so the id is required.", "example": 67244 } }, "required": ["action", "id"] }, "UpdatePhoneAttendeeWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_attendee", "description": "Action to perform, send a text message to the phone numbers of the attendees", "example": "sms_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "UpdatePhoneWhatsAppNumberWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "whatsapp_number", "description": "Action to perform, send a text message via whatsapp to a specific phone number", "example": "whatsapp_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "UpdateWhatsAppAttendeePhoneWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "whatsapp_attendee", "description": "Action to perform", "example": "whatsapp_attendee" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "message": { "description": "Message content for this step, send a text message via whatsapp to the phone numbers of the attendees", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] }, "phoneRequired": { "type": "boolean", "default": false, "description": "whether or not the attendees are required to provide their phone numbers when booking", "example": true }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "message"] }, "UpdatePhoneNumberWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": [ "email_host", "email_attendee", "email_address", "sms_attendee", "sms_number", "whatsapp_attendee", "whatsapp_number", "cal_ai_phone_call" ], "type": "string", "default": "sms_number", "description": "Action to perform, send a text message to a specific phone number", "example": "sms_number" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "recipient": { "type": "string", "description": "Recipient type", "example": "attendee", "enum": ["const", "attendee", "email", "phone_number"] }, "template": { "enum": ["reminder", "custom", "rescheduled", "completed", "rating", "cancelled"], "type": "string", "description": "Template type for the step. Case-insensitive: uppercase values (e.g. `REMINDER`) are normalized to lowercase server-side for backwards compat.", "example": "reminder" }, "sender": { "type": "string", "description": "Displayed sender name." }, "autoTranslateEnabled": { "type": "boolean", "description": "Whether to enable auto-translation of the workflow step content for attendees. Only available for organizations.", "example": false, "default": false }, "sourceLocale": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The source locale of the workflow step content used for auto-translation (e.g. 'en'). Defaults to the user's locale.", "example": "en" }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" }, "verifiedPhoneId": { "type": "number", "description": "Phone number if recipient is PHONE_NUMBER, required for actions SMS_NUMBER and WHATSAPP_NUMBER", "example": 3243434, "externalDocs": { "url": "https://cal.com/docs/api-reference/v2/organization-team-verified-resources/verify-a-phone-number-for-an-org-team" } }, "message": { "description": "Message content for this step", "allOf": [ { "$ref": "#/components/schemas/TextWorkflowMessageDto_2026_09_22" } ] }, "id": { "type": "number", "description": "Unique identifier of the step you want to update, if adding a new step do not provide this id", "example": 67244 } }, "required": ["action", "stepNumber", "recipient", "template", "sender", "verifiedPhoneId", "message"] }, "UpdateWebhookWorkflowStepDto_2026_09_22": { "type": "object", "properties": { "action": { "enum": ["webhook"], "type": "string", "description": "Action to perform", "example": "webhook" }, "stepNumber": { "type": "number", "description": "Step number in the workflow sequence", "example": 1 }, "id": { "type": "number", "description": "Workflow step id. Omit it when creating a new webhook step.", "example": 123 }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The HTTP or HTTPS URL that receives signed booking payloads. Omission keeps the saved URL.", "example": "https://example.com/webhook" }, "secret": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 255, "description": "HMAC key for X-Cal-Signature-256. Omission keeps the saved secret, null removes it, and a string replaces it. This secret is write-only and is never returned.", "writeOnly": true }, "pathId": { "type": "string", "format": "uuid", "description": "Id of the conditional path this step belongs to, so it only runs when that path's conditions match. It must name a path defined in this request or already persisted on an echoed gate. Omit it for a step that always runs.", "example": "3f4c11a2-9b7e-4d15-8f0a-2f7de41b6c01" } }, "required": ["action", "stepNumber"] }, "UpdateEventTypeWorkflowDto_2026_09_22": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the workflow", "example": "Platform Test Workflow" }, "activation": { "description": "Activation settings for the workflow", "allOf": [ { "$ref": "#/components/schemas/WorkflowActivationDto_2026_09_22" } ] }, "trigger": { "description": "Trigger configuration for the event-type workflow, allowed triggers are beforeEvent,eventCancelled,newEvent,afterEvent,rescheduleEvent,afterHostsCalVideoNoShow,afterGuestsCalVideoNoShow,bookingRejected,bookingRequested,bookingPaymentInitiated,bookingPaid,bookingNoShowUpdated", "oneOf": [ { "title": "Before Event", "$ref": "#/components/schemas/OnBeforeEventTriggerDto" }, { "title": "After Event", "$ref": "#/components/schemas/OnAfterEventTriggerDto" }, { "title": "Event Cancelled", "$ref": "#/components/schemas/OnCancelTriggerDto" }, { "title": "New Event", "$ref": "#/components/schemas/OnCreationTriggerDto" }, { "title": "Event Rescheduled", "$ref": "#/components/schemas/OnRescheduleTriggerDto" }, { "title": "After Guest No-Show", "$ref": "#/components/schemas/OnAfterCalVideoGuestsNoShowTriggerDto" }, { "title": "After Host No-Show", "$ref": "#/components/schemas/OnAfterCalVideoHostsNoShowTriggerDto" }, { "title": "Booking Rejected", "$ref": "#/components/schemas/OnRejectedTriggerDto" }, { "title": "Booking Requested", "$ref": "#/components/schemas/OnRequestedTriggerDto" }, { "title": "Booking Paid", "$ref": "#/components/schemas/OnPaidTriggerDto" }, { "title": "Booking Payment Initiated", "$ref": "#/components/schemas/OnPaymentInitiatedTriggerDto" }, { "title": "Booking No-Show Updated", "$ref": "#/components/schemas/OnNoShowUpdateTriggerDto" } ] }, "steps": { "type": "array", "minItems": 1, "description": "Steps to execute. This is the complete desired step list: omitted steps are deleted and omitted pathId makes a sending step unconditional. Omit steps entirely to preserve the graph. Existing delays and lead enrichment must still be echoed by id and keep their relative order.", "items": { "oneOf": [ { "title": "Email Address", "$ref": "#/components/schemas/UpdateEmailAddressWorkflowStepDto_2026_09_22" }, { "title": "Email Attendee", "$ref": "#/components/schemas/UpdateEmailAttendeeWorkflowStepDto_2026_09_22" }, { "title": "Email Host", "$ref": "#/components/schemas/UpdateEmailHostWorkflowStepDto_2026_09_22" }, { "title": "SMS Attendee", "$ref": "#/components/schemas/UpdatePhoneAttendeeWorkflowStepDto_2026_09_22" }, { "title": "WhatsApp Number", "$ref": "#/components/schemas/UpdatePhoneWhatsAppNumberWorkflowStepDto_2026_09_22" }, { "title": "WhatsApp Attendee", "$ref": "#/components/schemas/UpdateWhatsAppAttendeePhoneWorkflowStepDto_2026_09_22" }, { "title": "SMS Number", "$ref": "#/components/schemas/UpdatePhoneNumberWorkflowStepDto_2026_09_22" }, { "title": "Paths", "$ref": "#/components/schemas/UpdatePathsWorkflowStepDto_2026_09_22" }, { "title": "Filter", "$ref": "#/components/schemas/UpdateFilterWorkflowStepDto_2026_09_22" }, { "title": "Delay (existing step)", "$ref": "#/components/schemas/UpdateDelayWorkflowStepDto_2026_09_22" }, { "title": "Lead enrichment (existing step)", "$ref": "#/components/schemas/UpdateLeadEnrichmentWorkflowStepDto_2026_09_22" }, { "title": "Webhook", "$ref": "#/components/schemas/UpdateWebhookWorkflowStepDto_2026_09_22" } ] } } } }, "CreatePrivateLinkInput": { "type": "object", "properties": { "expiresAt": { "type": "string", "description": "Expiration date for time-based links", "format": "date-time", "example": "2024-12-31T23:59:59.000Z" }, "maxUsageCount": { "type": "number", "description": "Maximum number of times the link can be used. Pass `-1` to opt out of the count cap (the link is then gated only by `expiresAt`, or unbounded if that is also unset). If omitted and expiresAt is not provided, defaults to 1 (one time use).", "example": 10, "default": 1 } } }, "TimeBasedPrivateLinkOutput": { "type": "object", "properties": { "linkId": { "type": "string", "description": "The private link ID", "example": "abc123def456" }, "eventTypeId": { "type": "number", "description": "Event type ID this link belongs to", "example": 123 }, "isExpired": { "type": "boolean", "description": "Whether the link is currently expired", "example": false }, "bookingUrl": { "type": "string", "description": "Full booking URL for this private link (deprecated endpoints return hash-only URL without event slug)", "format": "uri", "example": "https://cal.com/d/abc123def456" }, "expiresAt": { "type": "string", "description": "Expiration date for this time-based link", "format": "date-time", "example": "2025-12-31T23:59:59.000Z" } }, "required": ["linkId", "eventTypeId", "isExpired", "bookingUrl", "expiresAt"] }, "UsageBasedPrivateLinkOutput": { "type": "object", "properties": { "linkId": { "type": "string", "description": "The private link ID", "example": "abc123def456" }, "eventTypeId": { "type": "number", "description": "Event type ID this link belongs to", "example": 123 }, "isExpired": { "type": "boolean", "description": "Whether the link is currently expired", "example": false }, "bookingUrl": { "type": "string", "description": "Full booking URL for this private link (deprecated endpoints return hash-only URL without event slug)", "format": "uri", "example": "https://cal.com/d/abc123def456" }, "maxUsageCount": { "type": "number", "description": "Maximum number of times this link can be used", "example": 10 }, "usageCount": { "type": "number", "description": "Current usage count for this link", "example": 3 } }, "required": ["linkId", "eventTypeId", "isExpired", "bookingUrl", "maxUsageCount", "usageCount"] }, "CreatePrivateLinkOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success" }, "data": { "description": "Created private link data (either time-based or usage-based)", "oneOf": [ { "title": "Time-Based Link", "$ref": "#/components/schemas/TimeBasedPrivateLinkOutput" }, { "title": "Usage-Based Link", "$ref": "#/components/schemas/UsageBasedPrivateLinkOutput" } ] } }, "required": ["status", "data"] }, "GetPrivateLinksOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success" }, "data": { "type": "array", "description": "Array of private links for the event type (mix of time-based and usage-based)", "items": { "oneOf": [ { "title": "Time-Based Link", "$ref": "#/components/schemas/TimeBasedPrivateLinkOutput" }, { "title": "Usage-Based Link", "$ref": "#/components/schemas/UsageBasedPrivateLinkOutput" } ] } } }, "required": ["status", "data"] }, "UpdatePrivateLinkOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success" }, "data": { "description": "Updated private link data (either time-based or usage-based)", "oneOf": [ { "title": "Time-Based Link", "$ref": "#/components/schemas/TimeBasedPrivateLinkOutput" }, { "title": "Usage-Based Link", "$ref": "#/components/schemas/UsageBasedPrivateLinkOutput" } ] } }, "required": ["status", "data"] }, "DeletePrivateLinkOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success" }, "data": { "type": "object", "description": "Deleted link information", "properties": { "linkId": { "type": "string", "example": "abc123def456" }, "message": { "type": "string", "example": "Private link deleted successfully" } } } }, "required": ["status", "data"] }, "GetDefaultScheduleOutput_2024_06_11": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ScheduleOutput_2024_06_11" } ] } }, "required": ["status", "data"] }, "TeamOutputDto": { "type": "object", "properties": { "id": { "type": "number" }, "parentId": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "logoUrl": { "type": "string", "format": "uri" }, "calVideoLogo": { "type": "string", "format": "uri" }, "appLogo": { "type": "string", "format": "uri" }, "appIconLogo": { "type": "string", "format": "uri" }, "bio": { "type": "string" }, "hideBranding": { "type": "boolean" }, "isOrganization": { "type": "boolean" }, "isPrivate": { "type": "boolean" }, "hideBookATeamMember": { "type": "boolean", "default": false }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } }, "theme": { "type": "string" }, "brandColor": { "type": "string" }, "darkBrandColor": { "type": "string" }, "bannerUrl": { "type": "string", "format": "uri" }, "timeFormat": { "type": "number" }, "timeZone": { "type": "string", "default": "Europe/London" }, "weekStart": { "type": "string", "default": "Sunday" } }, "required": ["id", "name", "isOrganization"] }, "GetTeamOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamOutputDto" } }, "required": ["status", "data"] }, "GetTeamsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamOutputDto" } } }, "required": ["status", "data"] }, "UpdateTeamOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamOutputDto" } }, "required": ["status", "data"] }, "GoogleServiceAccountKeyInput": { "type": "object", "properties": { "private_key": { "type": "string" }, "client_email": { "type": "string" }, "client_id": { "type": "string" } }, "required": ["private_key", "client_email", "client_id"] }, "CreateGoogleDelegationCredentialInput": { "type": "object", "properties": { "domain": { "type": "string" }, "workspacePlatformSlug": { "enum": ["google"], "type": "string" }, "serviceAccountKey": { "$ref": "#/components/schemas/GoogleServiceAccountKeyInput" } }, "required": ["domain", "workspacePlatformSlug", "serviceAccountKey"] }, "MicrosoftServiceAccountKeyInput": { "type": "object", "properties": { "private_key": { "type": "string" }, "tenant_id": { "type": "string" }, "client_id": { "type": "string" } }, "required": ["private_key", "tenant_id", "client_id"] }, "CreateMicrosoftDelegationCredentialInput": { "type": "object", "properties": { "domain": { "type": "string" }, "workspacePlatformSlug": { "enum": ["office365"], "type": "string" }, "serviceAccountKey": { "$ref": "#/components/schemas/MicrosoftServiceAccountKeyInput" }, "optOutAutoSecretRotation": { "type": "boolean", "description": "When true, Cal.com will not mint or promote managed Microsoft 365 client secrets for this delegation credential. Use this when the credential owner wants to rotate the active secret outside Cal.com." } }, "required": ["domain", "workspacePlatformSlug", "serviceAccountKey"] }, "WorkspacePlatformDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the workspace platform the delegation credential is configured for", "example": "Google" }, "slug": { "type": "string", "description": "The slug of the workspace platform the delegation credential is configured for", "example": "google" } }, "required": ["name", "slug"] }, "DelegationCredentialWithClientIdOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the delegation credential", "example": "clsx1234567890" }, "enabled": { "type": "boolean", "description": "Whether the delegation credential is currently enabled", "example": true }, "domain": { "type": "string", "description": "The email domain the delegation credential applies to", "example": "example.com" }, "organizationId": { "type": "number", "description": "The unique identifier of the organization the delegation credential belongs to", "example": 123 }, "workspacePlatform": { "$ref": "#/components/schemas/WorkspacePlatformDto" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was created", "example": "2024-04-01T00:00:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was last updated", "example": "2024-04-01T00:00:00.000Z" }, "serviceAccountClientId": { "type": "string", "nullable": true, "description": "The client id of the service account associated with the delegation credential. The service account's private key is never returned.", "example": "1234567890" } }, "required": [ "id", "enabled", "domain", "organizationId", "workspacePlatform", "createdAt", "updatedAt", "serviceAccountClientId" ] }, "GoogleDelegationCredentialWithClientIdOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the delegation credential", "example": "clsx1234567890" }, "enabled": { "type": "boolean", "description": "Whether the delegation credential is currently enabled", "example": true }, "domain": { "type": "string", "description": "The email domain the delegation credential applies to", "example": "example.com" }, "organizationId": { "type": "number", "description": "The unique identifier of the organization the delegation credential belongs to", "example": 123 }, "workspacePlatform": { "$ref": "#/components/schemas/WorkspacePlatformDto" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was created", "example": "2024-04-01T00:00:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was last updated", "example": "2024-04-01T00:00:00.000Z" }, "serviceAccountClientId": { "type": "string", "nullable": true, "description": "The client id of the service account associated with the delegation credential. The service account's private key is never returned.", "example": "1234567890" } }, "required": [ "id", "enabled", "domain", "organizationId", "workspacePlatform", "createdAt", "updatedAt", "serviceAccountClientId" ] }, "SecretDto": { "type": "object", "properties": { "expiresAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time the current active managed secret expires. Null if not yet known.", "example": "2024-10-01T00:00:00.000Z" } }, "required": ["expiresAt"] }, "PendingSecretDto": { "type": "object", "properties": { "createdAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time a replacement secret was minted and is pending validation/promotion. Null when there is no pending secret in flight.", "example": "2024-10-01T00:00:00.000Z" }, "expiresAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time the pending (not-yet-active) managed secret expires. Null when there is no pending secret in flight.", "example": "2024-10-01T00:00:00.000Z" } }, "required": ["createdAt", "expiresAt"] }, "MicrosoftDelegationCredentialWithClientIdOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the delegation credential", "example": "clsx1234567890" }, "enabled": { "type": "boolean", "description": "Whether the delegation credential is currently enabled", "example": true }, "domain": { "type": "string", "description": "The email domain the delegation credential applies to", "example": "example.com" }, "organizationId": { "type": "number", "description": "The unique identifier of the organization the delegation credential belongs to", "example": 123 }, "workspacePlatform": { "$ref": "#/components/schemas/WorkspacePlatformDto" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was created", "example": "2024-04-01T00:00:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was last updated", "example": "2024-04-01T00:00:00.000Z" }, "optOutAutoSecretRotation": { "type": "boolean", "description": "Whether Cal.com-managed Microsoft 365 client secret rotation is disabled for this delegation credential." }, "secretRotationBlocked": { "type": "boolean", "description": "Whether managed secret rotation is blocked after repeated failures and requires the reset-rotation endpoint before it will resume." }, "secret": { "description": "State of the current active managed secret. `expiresAt` is null if not yet known.", "allOf": [ { "$ref": "#/components/schemas/SecretDto" } ] }, "pendingSecret": { "description": "State of a replacement secret minted and pending validation/promotion. `createdAt` and `expiresAt` are null when there is no pending secret in flight.", "allOf": [ { "$ref": "#/components/schemas/PendingSecretDto" } ] }, "secretRotationErrorCode": { "nullable": true, "enum": [ "missing_permission", "tenant_lifetime_policy", "transient", "unknown", "pending_secret_mint_failed", "pending_secret_promotion_failed" ], "type": "string", "description": "Why the most recent secret rotation attempt failed, or which stage terminally failed, or null if rotation has not failed. This enum is open — new values may be added over time, so treat any value you don't recognize as `unknown`. See the Cal.com docs' 'Microsoft 365 (Azure) Secret Auto-Rotation' section for per-code remediation guidance.", "example": "missing_permission" }, "serviceAccountClientId": { "type": "string", "nullable": true, "description": "The client id of the service account associated with the delegation credential. The service account's private key is never returned.", "example": "1234567890" } }, "required": [ "id", "enabled", "domain", "organizationId", "workspacePlatform", "createdAt", "updatedAt", "optOutAutoSecretRotation", "secretRotationBlocked", "secret", "pendingSecret", "secretRotationErrorCode", "serviceAccountClientId" ] }, "GetDelegationCredentialsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success", "description": "The status of the request, either `success` or `error`" }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Google Service Account", "$ref": "#/components/schemas/GoogleDelegationCredentialWithClientIdOutput" }, { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftDelegationCredentialWithClientIdOutput" }, { "title": "Delegation Credential", "$ref": "#/components/schemas/DelegationCredentialWithClientIdOutput" } ] }, "description": "The list of delegation credentials belonging to the organization" } }, "required": ["status", "data"] }, "GetDelegationCredentialOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success", "description": "The status of the request, either `success` or `error`" }, "data": { "description": "The delegation credential matching the requested id", "oneOf": [ { "title": "Google Service Account", "$ref": "#/components/schemas/GoogleDelegationCredentialWithClientIdOutput" }, { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftDelegationCredentialWithClientIdOutput" }, { "title": "Delegation Credential", "$ref": "#/components/schemas/DelegationCredentialWithClientIdOutput" } ] } }, "required": ["status", "data"] }, "GoogleDelegationCredentialOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the delegation credential", "example": "clsx1234567890" }, "enabled": { "type": "boolean", "description": "Whether the delegation credential is currently enabled", "example": true }, "domain": { "type": "string", "description": "The email domain the delegation credential applies to", "example": "example.com" }, "organizationId": { "type": "number", "description": "The unique identifier of the organization the delegation credential belongs to", "example": 123 }, "workspacePlatform": { "$ref": "#/components/schemas/WorkspacePlatformDto" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was created", "example": "2024-04-01T00:00:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was last updated", "example": "2024-04-01T00:00:00.000Z" } }, "required": [ "id", "enabled", "domain", "organizationId", "workspacePlatform", "createdAt", "updatedAt" ] }, "MicrosoftDelegationCredentialOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the delegation credential", "example": "clsx1234567890" }, "enabled": { "type": "boolean", "description": "Whether the delegation credential is currently enabled", "example": true }, "domain": { "type": "string", "description": "The email domain the delegation credential applies to", "example": "example.com" }, "organizationId": { "type": "number", "description": "The unique identifier of the organization the delegation credential belongs to", "example": 123 }, "workspacePlatform": { "$ref": "#/components/schemas/WorkspacePlatformDto" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was created", "example": "2024-04-01T00:00:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the delegation credential was last updated", "example": "2024-04-01T00:00:00.000Z" }, "optOutAutoSecretRotation": { "type": "boolean", "description": "Whether Cal.com-managed Microsoft 365 client secret rotation is disabled for this delegation credential." }, "secretRotationBlocked": { "type": "boolean", "description": "Whether managed secret rotation is blocked after repeated failures and requires the reset-rotation endpoint before it will resume." }, "secret": { "description": "State of the current active managed secret. `expiresAt` is null if not yet known.", "allOf": [ { "$ref": "#/components/schemas/SecretDto" } ] }, "pendingSecret": { "description": "State of a replacement secret minted and pending validation/promotion. `createdAt` and `expiresAt` are null when there is no pending secret in flight.", "allOf": [ { "$ref": "#/components/schemas/PendingSecretDto" } ] }, "secretRotationErrorCode": { "nullable": true, "enum": [ "missing_permission", "tenant_lifetime_policy", "transient", "unknown", "pending_secret_mint_failed", "pending_secret_promotion_failed" ], "type": "string", "description": "Why the most recent secret rotation attempt failed, or which stage terminally failed, or null if rotation has not failed. This enum is open — new values may be added over time, so treat any value you don't recognize as `unknown`. See the Cal.com docs' 'Microsoft 365 (Azure) Secret Auto-Rotation' section for per-code remediation guidance.", "example": "missing_permission" } }, "required": [ "id", "enabled", "domain", "organizationId", "workspacePlatform", "createdAt", "updatedAt", "optOutAutoSecretRotation", "secretRotationBlocked", "secret", "pendingSecret", "secretRotationErrorCode" ] }, "CreateDelegationCredentialOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Google Service Account", "$ref": "#/components/schemas/GoogleDelegationCredentialOutput" }, { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftDelegationCredentialOutput" } ] } }, "required": ["status", "data"] }, "UpdateDelegationCredentialInput": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "serviceAccountKey": { "type": "array", "items": { "oneOf": [ { "title": "Google Service Account", "$ref": "#/components/schemas/GoogleServiceAccountKeyInput" }, { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftServiceAccountKeyInput" } ] } }, "optOutAutoSecretRotation": { "type": "boolean", "description": "When true, Cal.com will not mint or promote managed Microsoft 365 client secrets for this delegation credential. Use this when the credential owner wants to rotate the active secret outside Cal.com. Only supported for Microsoft/office365 delegation credentials; attempting to set this on a Google delegation credential returns a 400 error." } } }, "UpdateDelegationCredentialOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Google Service Account", "$ref": "#/components/schemas/GoogleDelegationCredentialOutput" }, { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftDelegationCredentialOutput" } ] } }, "required": ["status", "data"] }, "ResetDelegationCredentialRotationOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftDelegationCredentialOutput" } ], "allOf": [ { "$ref": "#/components/schemas/MicrosoftDelegationCredentialOutput" } ] } }, "required": ["status", "data"] }, "DelegationCredentialVerificationOutput": { "type": "object", "properties": { "verified": { "type": "boolean", "example": false, "description": "Whether the workspace accepted the delegation credential" }, "errorCode": { "type": "string", "nullable": true, "example": "CalendarAppDelegationCredentialInvalidGrantError", "description": "Classified reason the check failed; null when verified" }, "errorMessage": { "type": "string", "nullable": true, "example": "User might not exist in Google Workspace", "description": "Human-readable reason the check failed; null when verified" }, "impersonatedEmailMatchesDomain": { "type": "boolean", "example": false, "description": "Whether the authenticated user's email is on the delegation credential's domain. The check impersonates that user, so false usually explains a failure." } }, "required": ["verified", "errorCode", "errorMessage", "impersonatedEmailMatchesDomain"] }, "VerifyDelegationCredentialOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DelegationCredentialVerificationOutput" } }, "required": ["status", "data"] }, "DeleteDelegationCredentialOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Google Service Account", "$ref": "#/components/schemas/GoogleDelegationCredentialOutput" }, { "title": "Microsoft Service Account", "$ref": "#/components/schemas/MicrosoftDelegationCredentialOutput" } ] } }, "required": ["status", "data"] }, "CreateOrganizationInput": { "type": "object", "properties": { "apiKeyDaysValid": { "type": "number", "minimum": 1, "description": "For how many days is managed organization api key valid. Defaults to 30 days.", "example": 60, "default": 30 }, "apiKeyNeverExpires": { "type": "boolean", "description": "If true, organization api key never expires.", "example": true }, "name": { "type": "string", "minLength": 1, "description": "Name of the organization. Maximum 155 characters. Cannot contain links or URLs.", "example": "CalTeam", "maxLength": 155 }, "slug": { "type": "string", "description": "Organization slug in kebab-case - if not provided will be generated automatically based on name.", "example": "cal-tel" }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here.\nMetadata must have at most 50 keys, each key up to 40 characters.\nValues can be strings (up to 500 characters), numbers, or booleans.", "example": { "key": "value" } } }, "required": ["name"] }, "ManagedOrganizationWithApiKeyOutput": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } }, "apiKey": { "type": "string" } }, "required": ["id", "name", "apiKey"] }, "CreateManagedOrganizationOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ManagedOrganizationWithApiKeyOutput" } }, "required": ["status", "data"] }, "ManagedOrganizationOutput": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "key": "value" } } }, "required": ["id", "name"] }, "GetManagedOrganizationOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ManagedOrganizationOutput" } }, "required": ["status", "data"] }, "PaginationMetaDto": { "type": "object", "properties": { "totalItems": { "type": "number", "minimum": 0, "description": "The total number of items available across all pages, matching the query criteria.", "example": 123 }, "remainingItems": { "type": "number", "minimum": 0, "description": "The number of items remaining to be fetched *after* the current page. Calculated as: `totalItems - (skip + itemsPerPage)`.", "example": 103 }, "returnedItems": { "type": "number", "minimum": 0, "description": "The number of items returned in the current page.", "example": 10 }, "itemsPerPage": { "type": "number", "minimum": 1, "description": "The maximum number of items requested per page.", "example": 10 }, "currentPage": { "type": "number", "minimum": 1, "description": "The current page number being returned.", "example": 2 }, "totalPages": { "type": "number", "minimum": 0, "description": "The total number of pages available.", "example": 13 }, "hasNextPage": { "type": "boolean", "description": "Indicates if there is a subsequent page available after the current one.", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Indicates if there is a preceding page available before the current one.", "example": true } }, "required": [ "totalItems", "remainingItems", "returnedItems", "itemsPerPage", "currentPage", "totalPages", "hasNextPage", "hasPreviousPage" ] }, "GetManagedOrganizationsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedOrganizationOutput" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "UpdateOrganizationInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the organization. Maximum 155 characters. Cannot contain links or URLs.", "example": "CalTeam", "maxLength": 155 }, "metadata": { "type": "object", "additionalProperties": true, "description": "You can store any additional data you want here.\nMetadata must have at most 50 keys, each key up to 40 characters.\nValues can be strings (up to 500 characters), numbers, or booleans.", "example": { "key": "value" } } } }, "SecondaryDomainVerificationRecordOutput": { "type": "object", "properties": { "type": { "type": "string", "example": "TXT", "enum": ["TXT"] }, "name": { "type": "string", "example": "_cal-verification.acme.fr" }, "value": { "type": "string", "example": "cal-verification=3f1c0d7e9a2b4c6d8e0f1a2b3c4d5e6f" } }, "required": ["type", "name", "value"] }, "OrganizationSecondaryDomainOutput": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "domain": { "type": "string", "example": "acme.fr" }, "usernameSuffix": { "type": "string", "example": "fr", "description": "Usernames of members with this email domain end with -" }, "verified": { "type": "boolean", "example": false }, "verifiedAt": { "format": "date-time", "type": "string", "nullable": true, "example": null }, "createdAt": { "format": "date-time", "type": "string", "example": "2026-10-02T09:00:00.000Z" }, "verificationRecord": { "description": "DNS record that must be published to verify ownership of the domain", "allOf": [ { "$ref": "#/components/schemas/SecondaryDomainVerificationRecordOutput" } ] } }, "required": [ "id", "domain", "usernameSuffix", "verified", "verifiedAt", "createdAt", "verificationRecord" ] }, "OrganizationSecondaryDomainsResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationSecondaryDomainOutput" } } }, "required": ["status", "data"] }, "OrganizationSecondaryDomainResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrganizationSecondaryDomainOutput" } }, "required": ["status", "data"] }, "CreateOrganizationSecondaryDomainInput": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253, "example": "acme.fr", "description": "Domain to add as a secondary verified domain" }, "usernameSuffix": { "type": "string", "minLength": 1, "maxLength": 63, "example": "fr", "description": "Suffix appended to usernames of members with this email domain, e.g. john@acme.fr becomes john-fr. Defaults to the domain ending." } }, "required": ["domain"] }, "CreateOrgRoleInput": { "type": "object", "properties": { "color": { "type": "string", "description": "Color for the role (hex code)" }, "description": { "type": "string", "description": "Description of the role" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "*.*", "role.create", "role.read", "role.readTeamRoles", "role.readOrgRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.readOrgEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.create", "team.read", "team.readOrgTeams", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "organization.create", "organization.read", "organization.readMemberships", "organization.readManagedOrganizations", "organization.readDelegationCredentials", "organization.listMembers", "organization.listMembersPrivate", "organization.readMemberAuditLogs", "organization.invite", "organization.remove", "organization.manageBilling", "organization.changeMemberRole", "organization.impersonate", "organization.passwordReset", "organization.editUsers", "organization.update", "organization.delete", "booking.read", "booking.readOrgBookings", "booking.readRecordings", "booking.update", "booking.updateOrgBookings", "booking.reassignOrgPastBookings", "booking.readOrgAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "organization.attributes.read", "organization.attributes.update", "organization.attributes.delete", "organization.attributes.create", "organization.attributes.readSyncHistory", "organization.attributes.editUsers", "organization.attributes.readAuditLogs", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.readOrgRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readOrgAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.readOrgWebhooks", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.readOrgAvailability", "availability.updateTeamAvailability", "availability.updateOrgAvailability", "availability.readOrgAuditLogs", "ooo.readOrgOoo", "watchlist.create", "watchlist.read", "watchlist.update", "watchlist.delete", "featureOptIn.read", "featureOptIn.update", "organization.customDomain.create", "organization.customDomain.read", "organization.customDomain.update", "organization.customDomain.delete", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] }, "description": "Permissions for this role (format: resource.action). On update, this field replaces the entire permission set for the role (full replace). Use granular permission endpoints for one-by-one changes.", "example": ["eventType.read", "eventType.create", "booking.read"] }, "name": { "type": "string", "minLength": 1, "description": "Name of the role" } }, "required": ["name"] }, "OrgRoleOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the role" }, "name": { "type": "string", "description": "Name of the role" }, "color": { "type": "string", "nullable": true, "description": "Color for the role (hex code)" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" }, "organizationId": { "type": "number", "nullable": true, "description": "Organization ID this role belongs to" }, "type": { "enum": ["SYSTEM", "CUSTOM"], "type": "string", "description": "Type of role" }, "permissions": { "type": "array", "description": "Permissions assigned to this role in 'resource.action' format.", "example": ["booking.read", "eventType.create"], "items": { "type": "string", "enum": [ "*.*", "role.create", "role.read", "role.readTeamRoles", "role.readOrgRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.readOrgEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.create", "team.read", "team.readOrgTeams", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "organization.create", "organization.read", "organization.readMemberships", "organization.readManagedOrganizations", "organization.readDelegationCredentials", "organization.listMembers", "organization.listMembersPrivate", "organization.readMemberAuditLogs", "organization.invite", "organization.remove", "organization.manageBilling", "organization.changeMemberRole", "organization.impersonate", "organization.passwordReset", "organization.editUsers", "organization.update", "organization.delete", "booking.read", "booking.readOrgBookings", "booking.readRecordings", "booking.update", "booking.updateOrgBookings", "booking.reassignOrgPastBookings", "booking.readOrgAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "organization.attributes.read", "organization.attributes.update", "organization.attributes.delete", "organization.attributes.create", "organization.attributes.readSyncHistory", "organization.attributes.editUsers", "organization.attributes.readAuditLogs", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.readOrgRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readOrgAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.readOrgWebhooks", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.readOrgAvailability", "availability.updateTeamAvailability", "availability.updateOrgAvailability", "availability.readOrgAuditLogs", "ooo.readOrgOoo", "watchlist.create", "watchlist.read", "watchlist.update", "watchlist.delete", "featureOptIn.read", "featureOptIn.update", "organization.customDomain.create", "organization.customDomain.read", "organization.customDomain.update", "organization.customDomain.delete", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] } }, "createdAt": { "type": "string", "description": "When the role was created" }, "updatedAt": { "type": "string", "description": "When the role was last updated" } }, "required": ["id", "name", "type", "permissions", "createdAt", "updatedAt"] }, "CreateOrgRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrgRoleOutput" } }, "required": ["status", "data"] }, "GetOrgRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrgRoleOutput" } }, "required": ["status", "data"] }, "GetAllOrgRolesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgRoleOutput" } } }, "required": ["status", "data"] }, "UpdateOrgRoleInput": { "type": "object", "properties": { "color": { "type": "string", "description": "Color for the role (hex code)" }, "description": { "type": "string", "description": "Description of the role" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "*.*", "role.create", "role.read", "role.readTeamRoles", "role.readOrgRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.readOrgEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.create", "team.read", "team.readOrgTeams", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "organization.create", "organization.read", "organization.readMemberships", "organization.readManagedOrganizations", "organization.readDelegationCredentials", "organization.listMembers", "organization.listMembersPrivate", "organization.readMemberAuditLogs", "organization.invite", "organization.remove", "organization.manageBilling", "organization.changeMemberRole", "organization.impersonate", "organization.passwordReset", "organization.editUsers", "organization.update", "organization.delete", "booking.read", "booking.readOrgBookings", "booking.readRecordings", "booking.update", "booking.updateOrgBookings", "booking.reassignOrgPastBookings", "booking.readOrgAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "organization.attributes.read", "organization.attributes.update", "organization.attributes.delete", "organization.attributes.create", "organization.attributes.readSyncHistory", "organization.attributes.editUsers", "organization.attributes.readAuditLogs", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.readOrgRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readOrgAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.readOrgWebhooks", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.readOrgAvailability", "availability.updateTeamAvailability", "availability.updateOrgAvailability", "availability.readOrgAuditLogs", "ooo.readOrgOoo", "watchlist.create", "watchlist.read", "watchlist.update", "watchlist.delete", "featureOptIn.read", "featureOptIn.update", "organization.customDomain.create", "organization.customDomain.read", "organization.customDomain.update", "organization.customDomain.delete", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] }, "description": "Permissions for this role (format: resource.action). On update, this field replaces the entire permission set for the role (full replace). Use granular permission endpoints for one-by-one changes.", "example": ["eventType.read", "eventType.create", "booking.read"] }, "name": { "type": "string", "minLength": 1, "description": "Name of the role" } } }, "UpdateOrgRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrgRoleOutput" } }, "required": ["status", "data"] }, "DeleteOrgRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrgRoleOutput" } }, "required": ["status", "data"] }, "CreateOrgRolePermissionsInput": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string", "enum": [ "*.*", "role.create", "role.read", "role.readTeamRoles", "role.readOrgRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.readOrgEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.create", "team.read", "team.readOrgTeams", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "organization.create", "organization.read", "organization.readMemberships", "organization.readManagedOrganizations", "organization.readDelegationCredentials", "organization.listMembers", "organization.listMembersPrivate", "organization.readMemberAuditLogs", "organization.invite", "organization.remove", "organization.manageBilling", "organization.changeMemberRole", "organization.impersonate", "organization.passwordReset", "organization.editUsers", "organization.update", "organization.delete", "booking.read", "booking.readOrgBookings", "booking.readRecordings", "booking.update", "booking.updateOrgBookings", "booking.reassignOrgPastBookings", "booking.readOrgAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "organization.attributes.read", "organization.attributes.update", "organization.attributes.delete", "organization.attributes.create", "organization.attributes.readSyncHistory", "organization.attributes.editUsers", "organization.attributes.readAuditLogs", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.readOrgRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readOrgAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.readOrgWebhooks", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.readOrgAvailability", "availability.updateTeamAvailability", "availability.updateOrgAvailability", "availability.readOrgAuditLogs", "ooo.readOrgOoo", "watchlist.create", "watchlist.read", "watchlist.update", "watchlist.delete", "featureOptIn.read", "featureOptIn.update", "organization.customDomain.create", "organization.customDomain.read", "organization.customDomain.update", "organization.customDomain.delete", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] }, "description": "Permissions to add (format: resource.action)", "example": ["eventType.read", "booking.read"] } }, "required": ["permissions"] }, "GetOrgRolePermissionsOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" } } }, "required": ["status", "data"] }, "CreateTeamRoleInput": { "type": "object", "properties": { "color": { "type": "string", "description": "Color for the role (hex code)" }, "description": { "type": "string", "description": "Description of the role" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "role.create", "role.read", "role.readTeamRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.read", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "booking.read", "booking.readTeamBookings", "booking.readRecordings", "booking.update", "booking.updateTeamBookings", "booking.reassignTeamPastBookings", "booking.readTeamAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readTeamAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.updateTeamAvailability", "featureOptIn.read", "featureOptIn.update", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] }, "description": "Permissions for this role (format: resource.action). On update, this field replaces the entire permission set for the role (full replace). Use granular permission endpoints for one-by-one changes.", "example": ["eventType.read", "eventType.create", "booking.read"] }, "name": { "type": "string", "minLength": 1, "description": "Name of the role" } }, "required": ["name"] }, "TeamRoleOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the role" }, "name": { "type": "string", "description": "Name of the role" }, "color": { "type": "string", "nullable": true, "description": "Color for the role (hex code)" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" }, "teamId": { "type": "number", "nullable": true, "description": "Team ID this role belongs to" }, "type": { "enum": ["SYSTEM", "CUSTOM"], "type": "string", "description": "Type of role" }, "permissions": { "type": "array", "description": "Permissions assigned to this role in 'resource.action' format.", "example": ["booking.read", "eventType.create"], "items": { "type": "string", "enum": [ "role.create", "role.read", "role.readTeamRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.read", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "booking.read", "booking.readTeamBookings", "booking.readRecordings", "booking.update", "booking.updateTeamBookings", "booking.reassignTeamPastBookings", "booking.readTeamAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readTeamAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.updateTeamAvailability", "featureOptIn.read", "featureOptIn.update", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] } }, "createdAt": { "type": "string", "description": "When the role was created" }, "updatedAt": { "type": "string", "description": "When the role was last updated" } }, "required": ["id", "name", "type", "permissions", "createdAt", "updatedAt"] }, "CreateTeamRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamRoleOutput" } }, "required": ["status", "data"] }, "GetTeamRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamRoleOutput" } }, "required": ["status", "data"] }, "GetAllTeamRolesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRoleOutput" } } }, "required": ["status", "data"] }, "UpdateTeamRoleInput": { "type": "object", "properties": { "color": { "type": "string", "description": "Color for the role (hex code)" }, "description": { "type": "string", "description": "Description of the role" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "role.create", "role.read", "role.readTeamRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.read", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "booking.read", "booking.readTeamBookings", "booking.readRecordings", "booking.update", "booking.updateTeamBookings", "booking.reassignTeamPastBookings", "booking.readTeamAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readTeamAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.updateTeamAvailability", "featureOptIn.read", "featureOptIn.update", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] }, "description": "Permissions for this role (format: resource.action). On update, this field replaces the entire permission set for the role (full replace). Use granular permission endpoints for one-by-one changes.", "example": ["eventType.read", "eventType.create", "booking.read"] }, "name": { "type": "string", "minLength": 1, "description": "Name of the role" } } }, "UpdateTeamRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamRoleOutput" } }, "required": ["status", "data"] }, "DeleteTeamRoleOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamRoleOutput" } }, "required": ["status", "data"] }, "CreateTeamRolePermissionsInput": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string", "enum": [ "role.create", "role.read", "role.readTeamRoles", "role.update", "role.delete", "eventType.create", "eventType.read", "eventType.readTeamEventTypes", "eventType.update", "eventType.delete", "calEvent.create", "calEvent.read", "calEvent.update", "calEvent.delete", "team.read", "team.readTeamSettings", "team.readConferencing", "team.readVerifiedResources", "team.readMemberships", "team.update", "team.delete", "team.invite", "team.remove", "team.listMembers", "team.listMembersPrivate", "team.changeMemberRole", "team.impersonate", "booking.read", "booking.readTeamBookings", "booking.readRecordings", "booking.update", "booking.updateTeamBookings", "booking.reassignTeamPastBookings", "booking.readTeamAuditLogs", "insights.read", "workflow.create", "workflow.read", "workflow.readTeamWorkflows", "workflow.update", "workflow.delete", "routingForm.create", "routingForm.read", "routingForm.readTeamRoutingForms", "routingForm.update", "routingForm.delete", "routingForm.readTeamAuditLogs", "routingForm.readResponsePii", "webhook.create", "webhook.read", "webhook.update", "webhook.delete", "availability.readTeamAvailability", "availability.updateTeamAvailability", "featureOptIn.read", "featureOptIn.update", "app.read", "tag.create", "tag.update", "tag.delete", "savedView.create", "savedView.update", "savedView.delete" ] }, "description": "Permissions to add (format: resource.action)", "example": ["eventType.read", "booking.read"] } }, "required": ["permissions"] }, "GetTeamRolePermissionsOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" } } }, "required": ["status", "data"] }, "RoutingFormResponseOutput": { "type": "object", "properties": { "id": { "type": "number" }, "formId": { "type": "string" }, "formFillerId": { "type": "string" }, "routedToBookingUid": { "type": "string" }, "response": { "type": "object", "additionalProperties": true, "example": { "f00b26df-f54b-4985-8d98-17c5482c6a24": { "label": "participant", "value": "mamut" } } }, "createdAt": { "format": "date-time", "type": "string" } }, "required": ["id", "formId", "formFillerId", "routedToBookingUid", "response", "createdAt"] }, "GetRoutingFormResponsesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingFormResponseOutput" } } }, "required": ["status", "data"] }, "SlotsOutput_2024_09_04": { "type": "object", "properties": {} }, "RangeSlotsOutput_2024_09_04": { "type": "object", "properties": {} }, "Routing": { "type": "object", "properties": { "queuedResponseId": { "type": "string", "nullable": true, "description": "The ID of the queued form response. Only present if the form response was queued.", "example": "123" }, "responseId": { "type": "number", "nullable": true, "description": "The ID of the routing form response.", "example": 123 }, "teamMemberIds": { "description": "Array of team member IDs that were routed to handle this booking.", "example": [101, 102], "type": "array", "items": { "type": "number" } }, "teamMemberEmail": { "type": "string", "description": "The email of the team member assigned to handle this booking.", "example": "john.doe@example.com" }, "skipContactOwner": { "type": "boolean", "description": "Whether to skip contact owner assignment from CRM integration.", "example": true }, "crmAppSlug": { "type": "string", "description": "The CRM application slug for integration.", "example": "salesforce" }, "crmOwnerRecordType": { "type": "string", "description": "The CRM owner record type for contact assignment.", "example": "Account" }, "crmRecordOwnerFallbackTeamMemberIds": { "description": "Eligible CRM owner fallback team member IDs to pass to the booking API.", "example": [103, 104], "type": "array", "items": { "type": "number" } }, "crmRecordOwnerFallbackMode": { "type": "string", "enum": ["relationship", "attributeRules"], "description": "The CRM owner fallback strategy used for this routing result.", "example": "relationship" } }, "required": ["teamMemberIds"] }, "CreateRoutingFormResponseOutputData": { "type": "object", "properties": { "eventTypeId": { "type": "number", "description": "The ID of the event type that was routed to.", "example": 123 }, "routing": { "description": "The routing information that could be passed as is to the booking API.", "example": { "eventTypeId": 123, "routing": { "teamMemberIds": [101, 102], "teamMemberEmail": "john.doe@example.com", "skipContactOwner": true, "crmRecordOwnerFallbackTeamMemberIds": [103, 104], "crmRecordOwnerFallbackMode": "attributeRules" } }, "allOf": [ { "$ref": "#/components/schemas/Routing" } ] }, "routingCustomMessage": { "type": "string", "description": "A custom message to be displayed to the user in case of routing to a custom page.", "example": "This is a custom message." }, "routingExternalRedirectUrl": { "type": "string", "description": "The external redirect URL to be used in case of routing to a non cal.com event type URL.", "example": "https://example.com/" }, "slots": { "additionalProperties": true, "oneOf": [ { "title": "Time Slots", "$ref": "#/components/schemas/SlotsOutput_2024_09_04" }, { "title": "Slot Ranges", "$ref": "#/components/schemas/RangeSlotsOutput_2024_09_04" } ] } } }, "CreateRoutingFormResponseOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/CreateRoutingFormResponseOutputData" } }, "required": ["status", "data"] }, "UpdateRoutingFormResponseInput": { "type": "object", "properties": { "response": { "type": "object", "additionalProperties": true, "description": "The updated response data" } } }, "UpdateRoutingFormResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/RoutingFormResponseOutput" } }, "required": ["status", "data"] }, "RoutingFormOutput": { "type": "object", "properties": { "name": { "type": "string", "example": "My Form" }, "description": { "type": "string", "nullable": true, "example": "This is the description." }, "position": { "type": "number", "example": 0 }, "routes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Routing form routes configuration" }, "createdAt": { "type": "string", "example": "2024-03-28T10:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "example": "2024-03-28T10:00:00.000Z", "format": "date-time" }, "fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Routing form fields configuration" }, "userId": { "type": "number", "example": 2313 }, "teamId": { "type": "number", "nullable": true, "example": 4214321 }, "disabled": { "type": "boolean", "example": false }, "settings": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Routing form settings" }, "id": { "type": "string" } }, "required": [ "name", "description", "position", "createdAt", "updatedAt", "userId", "teamId", "disabled", "id" ] }, "GetRoutingFormsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingFormOutput" } } }, "required": ["status", "data"] }, "CreateTeamRoutingFormInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Inbound sales" }, "description": { "type": "string", "maxLength": 3000, "example": "Routes inbound leads to the right sales rep" } }, "required": ["name"] }, "TeamRoutingFormQuestionOptionOutput": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "a1b2c3d4-..." }, "label": { "type": "string", "example": "51-200" } }, "required": ["id", "label"] }, "TeamRoutingFormQuestionOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4-..." }, "label": { "type": "string", "example": "Company size" }, "identifier": { "type": "string", "example": "companySize", "description": "The key used to answer this question in a routing form response" }, "type": { "type": "string", "example": "select" }, "required": { "type": "boolean", "example": true }, "hidden": { "type": "boolean", "example": false, "description": "Not shown to the booker; the answer comes from a URL parameter named after the identifier" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRoutingFormQuestionOptionOutput" } } }, "required": ["id", "label", "identifier", "type", "required", "hidden", "options"] }, "TeamRoutingFormRouteActionOutput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["customPageMessage", "externalRedirectUrl", "eventTypeRedirectUrl"], "description": "For eventTypeRedirectUrl, value is the `team-slug/event-slug` path of the routed-to event type" }, "value": { "type": "string", "example": "acme/discovery-call" }, "eventTypeId": { "type": "number", "nullable": true, "example": 123 } }, "required": ["type", "value", "eventTypeId"] }, "TeamRoutingFormRouteOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4-..." }, "name": { "type": "string", "nullable": true, "example": "Enterprise leads" }, "kind": { "type": "string", "enum": ["route", "router", "fallback"] }, "action": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/TeamRoutingFormRouteActionOutput" } ] }, "conditions": { "type": "string", "nullable": true, "example": "\"Company size\" equals \"51-200\"", "description": "Human-readable description of the conditions a submission must match" } }, "required": ["id", "name", "kind", "action", "conditions"] }, "TeamRoutingFormOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4-..." }, "name": { "type": "string", "example": "My Form" }, "description": { "type": "string", "nullable": true, "example": "This is the description." }, "disabled": { "type": "boolean", "example": false }, "teamId": { "type": "number", "example": 4214321 }, "updatedAt": { "type": "string", "example": "2024-03-28T10:00:00.000Z", "format": "date-time", "description": "Last modification time; required to apply route and question edits so concurrent changes are detected" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRoutingFormQuestionOutput" } }, "routes": { "description": "Routes in evaluation order", "type": "array", "items": { "$ref": "#/components/schemas/TeamRoutingFormRouteOutput" } }, "summary": { "description": "Human-readable overview of the form's questions and routing", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "disabled", "teamId", "updatedAt", "questions", "routes", "summary" ] }, "GetTeamRoutingFormOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamRoutingFormOutput" } }, "required": ["status", "data"] }, "TeamRoutingFormHistoryActorOutput": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Ada Lovelace", "description": "Display name of who made the change; null when they have no name" } }, "required": ["name"] }, "TeamRoutingFormHistoryEntryOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b" }, "timestamp": { "type": "string", "example": "2026-10-12T10:00:00.000Z", "format": "date-time" }, "actor": { "$ref": "#/components/schemas/TeamRoutingFormHistoryActorOutput" }, "changes": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "example": [ { "field": "name", "label": "Name", "type": "scalar", "previousValue": "Intake", "newValue": "Sales intake" } ], "description": "What changed. Every change has `field`, `label` and `type`: `scalar` adds `previousValue` and `newValue` (user ids for `sendUpdatesTo`); `list` (questions, routes) adds `added`, `removed` and `updated`; `object` nests more `changes`; `raqbTree` (route conditions) adds a `tree`; `created` and `deleted` mark the form's creation and deletion." } }, "required": ["id", "timestamp", "actor", "changes"] }, "TeamRoutingFormHistoryPaginationOutput": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "example": "019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b", "description": "Pass as `cursor` to fetch older entries; null when there are none" }, "hasMore": { "type": "boolean", "example": false } }, "required": ["nextCursor", "hasMore"] }, "GetTeamRoutingFormHistoryOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "description": "Newest first", "type": "array", "items": { "$ref": "#/components/schemas/TeamRoutingFormHistoryEntryOutput" } }, "pagination": { "$ref": "#/components/schemas/TeamRoutingFormHistoryPaginationOutput" } }, "required": ["status", "data", "pagination"] }, "EventTypeRedirectActionInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["eventTypeRedirectUrl"] }, "eventTypeSlug": { "type": "string", "example": "acme/discovery-call" } }, "required": ["type", "eventTypeSlug"] }, "CustomPageMessageActionInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["customPageMessage"] }, "message": { "type": "string", "example": "Thanks for your interest" } }, "required": ["type", "message"] }, "ExternalRedirectUrlActionInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["externalRedirectUrl"] }, "url": { "type": "string", "format": "uri", "example": "https://example.com/booking" } }, "required": ["type", "url"] }, "DraftConditionInput": { "type": "object", "properties": { "field": { "type": "string", "example": "Company size" }, "operator": { "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "is_empty", "is_not_empty", "greater_than", "less_than", "greater_or_equal", "less_or_equal", "between", "all_in", "not_all_in" ], "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ] } }, "required": ["field", "operator"] }, "DraftMemberFilterConditionInput": { "type": "object", "properties": { "attribute": { "type": "string", "example": "Department" }, "operator": { "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "is_empty", "is_not_empty", "greater_than", "less_than", "greater_or_equal", "less_or_equal", "between", "all_in", "not_all_in" ], "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ] } }, "required": ["attribute", "operator"] }, "DraftMemberFilterInput": { "type": "object", "properties": { "match": { "default": "all", "type": "string", "enum": ["all", "any"] }, "conditions": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/DraftMemberFilterConditionInput" } } }, "required": ["conditions"] }, "DraftRouteInput": { "type": "object", "properties": { "name": { "type": "string", "example": "Enterprise" }, "match": { "default": "all", "type": "string", "enum": ["all", "any"] }, "conditions": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/DraftConditionInput" } }, "action": { "oneOf": [ { "$ref": "#/components/schemas/EventTypeRedirectActionInput" }, { "$ref": "#/components/schemas/CustomPageMessageActionInput" }, { "$ref": "#/components/schemas/ExternalRedirectUrlActionInput" } ] }, "memberFilter": { "$ref": "#/components/schemas/DraftMemberFilterInput" }, "fallbackMemberFilter": { "description": "The hosts to use when memberFilter matches nobody. The route needs attribute rules: send memberFilter too, or replace a route that already has them. On replace, omit it to keep the stored fallback rules.", "allOf": [ { "$ref": "#/components/schemas/DraftMemberFilterInput" } ] } }, "required": ["conditions", "action"] }, "AddRouteOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["add"] }, "route": { "$ref": "#/components/schemas/DraftRouteInput" }, "position": { "type": "number", "minimum": 0 } }, "required": ["type", "route"] }, "ReplaceRouteOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["replace"] }, "routeId": { "type": "string", "example": "route-enterprise" }, "route": { "$ref": "#/components/schemas/DraftRouteInput" } }, "required": ["type", "routeId", "route"] }, "RemoveRouteOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["remove"] }, "routeId": { "type": "string", "example": "route-enterprise" } }, "required": ["type", "routeId"] }, "MoveRouteOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["move"] }, "routeId": { "type": "string", "example": "route-enterprise" }, "position": { "type": "number", "minimum": 0 } }, "required": ["type", "routeId", "position"] }, "SetFallbackOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["setFallback"] }, "action": { "oneOf": [ { "$ref": "#/components/schemas/EventTypeRedirectActionInput" }, { "$ref": "#/components/schemas/CustomPageMessageActionInput" }, { "$ref": "#/components/schemas/ExternalRedirectUrlActionInput" } ] } }, "required": ["type", "action"] }, "RouteExampleInput": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ] }, "example": { "Company size": "51-200" } }, "expectedRoute": { "type": "string", "nullable": true, "description": "The route's exact name, or the event-type slug it redirects to. Null when the answers should fall through to the fallback; a route id is also accepted.", "example": "route-enterprise" } }, "required": ["answers", "expectedRoute"] }, "EditTeamRoutingFormRoutesInput": { "type": "object", "properties": { "operations": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "oneOf": [ { "$ref": "#/components/schemas/AddRouteOperationInput" }, { "$ref": "#/components/schemas/ReplaceRouteOperationInput" }, { "$ref": "#/components/schemas/RemoveRouteOperationInput" }, { "$ref": "#/components/schemas/MoveRouteOperationInput" }, { "$ref": "#/components/schemas/SetFallbackOperationInput" } ] } }, "examples": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/RouteExampleInput" } }, "dryRun": { "type": "boolean", "default": true, "description": "Preview changes without saving. Defaults to true." }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Required when dryRun is false: the updatedAt from the preview or from get_routing_form." } }, "required": ["operations"] }, "EditTeamRoutingFormRouteChangeOutput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["add", "replace", "remove", "move", "setFallback", "addMissingFallback"] }, "routeId": { "type": "string", "example": "route-enterprise" }, "description": { "type": "string", "example": "Added route \"Enterprise\" at position 0." } }, "required": ["type", "routeId", "description"] }, "EditTeamRoutingFormRoutesRouteOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4-..." }, "name": { "type": "string", "nullable": true, "example": "Enterprise leads" }, "kind": { "type": "string", "enum": ["route", "router", "fallback"] }, "action": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/TeamRoutingFormRouteActionOutput" } ] }, "conditions": { "type": "string", "nullable": true, "example": "\"Company size\" equals \"51-200\"", "description": "Human-readable description of the conditions a submission must match" }, "advancedRouting": { "description": "Advanced routing settings on the route, e.g. attribute-based team member routing; empty for routers", "type": "array", "items": { "type": "string" } } }, "required": ["id", "name", "kind", "action", "conditions", "advancedRouting"] }, "EditTeamRoutingFormRoutesDataOutput": { "type": "object", "properties": { "formId": { "type": "string", "example": "a1b2c3d4-..." }, "dryRun": { "type": "boolean", "example": true }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/EditTeamRoutingFormRouteChangeOutput" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "before": { "type": "array", "items": { "$ref": "#/components/schemas/EditTeamRoutingFormRoutesRouteOutput" } }, "after": { "type": "array", "items": { "$ref": "#/components/schemas/EditTeamRoutingFormRoutesRouteOutput" } }, "updatedAt": { "type": "string", "example": "2024-03-28T10:00:00.000Z", "format": "date-time" } }, "required": ["formId", "dryRun", "changes", "warnings", "before", "after", "updatedAt"] }, "EditTeamRoutingFormRoutesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EditTeamRoutingFormRoutesDataOutput" } }, "required": ["status", "data"] }, "NewRoutingFormFieldInput": { "type": "object", "properties": { "label": { "type": "string", "example": "Lead source" }, "type": { "enum": ["text", "number", "textarea", "select", "multiselect", "phone", "email"], "type": "string", "example": "select" }, "required": { "type": "boolean", "default": false }, "hidden": { "type": "boolean", "default": false, "description": "Not shown to the booker; the answer comes from a URL parameter named after the identifier. A hidden question can't be required." }, "identifier": { "type": "string", "example": "lead_source", "description": "The key that prefills and stores the answer. Defaults to the label." }, "options": { "example": ["Partner", "Website"], "description": "Option labels in display order. Required for select and multiselect, forbidden otherwise.", "type": "array", "items": { "type": "string" } } }, "required": ["label", "type"] }, "AddFieldOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["add"] }, "field": { "$ref": "#/components/schemas/NewRoutingFormFieldInput" }, "position": { "type": "number", "minimum": 0, "example": 0, "description": "0-based position among the form's questions. Appends when omitted." } }, "required": ["type", "field"] }, "RoutingFormFieldOptionInput": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "a1b2c3d4-...", "description": "The option id from get_routing_form. Omit it for a new option." }, "label": { "type": "string", "example": "Partner" } }, "required": ["label"] }, "RoutingFormFieldUpdateInput": { "type": "object", "properties": { "label": { "type": "string", "example": "Lead source" }, "identifier": { "type": "string", "example": "lead_source" }, "required": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "A hidden question can't be required." }, "options": { "minItems": 1, "description": "The complete option list in display order. A listed id keeps that option, renamed to its label; an existing option left out is removed.", "type": "array", "items": { "$ref": "#/components/schemas/RoutingFormFieldOptionInput" } } } }, "UpdateFieldOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["update"] }, "fieldId": { "type": "string", "example": "a1b2c3d4-...", "description": "The question id from get_routing_form" }, "field": { "description": "Only the properties to change", "allOf": [ { "$ref": "#/components/schemas/RoutingFormFieldUpdateInput" } ] } }, "required": ["type", "fieldId", "field"] }, "RemoveFieldOperationInput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["remove"] }, "fieldId": { "type": "string", "example": "a1b2c3d4-...", "description": "The question id from get_routing_form" } }, "required": ["type", "fieldId"] }, "EditTeamRoutingFormFieldsInput": { "type": "object", "properties": { "operations": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "oneOf": [ { "title": "Add question", "$ref": "#/components/schemas/AddFieldOperationInput" }, { "title": "Update question", "$ref": "#/components/schemas/UpdateFieldOperationInput" }, { "title": "Remove question", "$ref": "#/components/schemas/RemoveFieldOperationInput" } ] } }, "dryRun": { "type": "boolean", "default": true, "description": "Preview changes without saving. Defaults to true." }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Required when dryRun is false: the updatedAt from the preview or from get_routing_form." } }, "required": ["operations"] }, "EditTeamRoutingFormFieldChangeOutput": { "type": "object", "properties": { "type": { "type": "string", "enum": ["add", "update", "remove"] }, "fieldId": { "type": "string", "example": "a1b2c3d4-..." }, "description": { "type": "string", "example": "Added question \"Lead source\" (text) at position 2." } }, "required": ["type", "fieldId", "description"] }, "EditTeamRoutingFormFieldsDataOutput": { "type": "object", "properties": { "formId": { "type": "string", "example": "a1b2c3d4-..." }, "dryRun": { "type": "boolean", "example": true }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/EditTeamRoutingFormFieldChangeOutput" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "before": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRoutingFormQuestionOutput" } }, "after": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRoutingFormQuestionOutput" } }, "updatedAt": { "type": "string", "example": "2024-03-28T10:00:00.000Z", "format": "date-time", "description": "Dry run: the form's current updatedAt, to send back as expectedUpdatedAt. Apply: the saved form's." } }, "required": ["formId", "dryRun", "changes", "warnings", "before", "after", "updatedAt"] }, "EditTeamRoutingFormFieldsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EditTeamRoutingFormFieldsDataOutput" } }, "required": ["status", "data"] }, "ResponseSlotsOutputData": { "type": "object", "properties": { "eventTypeId": { "type": "number" }, "slots": { "additionalProperties": true, "oneOf": [ { "title": "Time Slots", "$ref": "#/components/schemas/SlotsOutput_2024_09_04" }, { "title": "Slot Ranges", "$ref": "#/components/schemas/RangeSlotsOutput_2024_09_04" } ] } }, "required": ["eventTypeId", "slots"] }, "ResponseSlotsOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/ResponseSlotsOutputData" } }, "required": ["status", "data"] }, "ReserveSlotInput_2024_09_04": { "type": "object", "properties": { "eventTypeId": { "type": "number", "example": 1, "description": "The ID of the event type for which slot should be reserved." }, "slotStart": { "type": "string", "example": "2024-09-04T09:00:00Z", "description": "ISO 8601 datestring in UTC timezone representing available slot.", "format": "date-time" }, "slotDuration": { "type": "number", "example": 30, "description": "By default slot duration is equal to event type length, but if you want to reserve a slot for an event type that has a variable length you can specify it here as a number in minutes. If you don't have this set explicitly that event type can have one of many lengths you can omit this." }, "reservationDuration": { "type": "number", "example": 5, "description": "ONLY for authenticated requests with api key, access token or OAuth credentials (ID + secret).\n \n For how many minutes the slot should be reserved - for this long time noone else can book this event type at `start` time. If not provided, defaults to 5 minutes." } }, "required": ["eventTypeId", "slotStart"] }, "ReserveSlotOutput_2024_09_04": { "type": "object", "properties": { "eventTypeId": { "type": "number", "example": 1, "description": "The ID of the event type for which slot was reserved." }, "slotStart": { "type": "string", "example": "2024-09-04T09:00:00Z", "description": "ISO 8601 datestring in UTC timezone representing available slot.", "format": "date-time" }, "slotEnd": { "type": "string", "example": "2024-09-04T10:00:00Z", "description": "ISO 8601 datestring in UTC timezone representing slot end.", "format": "date-time" }, "slotDuration": { "type": "number", "example": 30, "description": "By default slot duration is equal to event type length, but if you want to reserve a slot for an event type that has a variable length you can specify it here. If you don't have this set explicitly that event type can have one of many lengths you can omit this." }, "reservationUid": { "type": "string", "example": "e84be5a3-4696-49e3-acc7-b2f3999c3b94", "description": "The unique identifier of the reservation. Use it to update, get or delete the reservation." }, "reservationDuration": { "type": "number", "example": 5, "description": "For how many minutes the slot is reserved - for this long time noone else can book this event type at `start` time." }, "reservationUntil": { "type": "string", "example": "2023-09-04T10:00:00Z", "description": "ISO 8601 datestring in UTC timezone representing time until which the slot is reserved.", "format": "date-time" } }, "required": [ "eventTypeId", "slotStart", "slotEnd", "slotDuration", "reservationUid", "reservationDuration", "reservationUntil" ] }, "ReserveSlotOutputResponse_2024_09_04": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/ReserveSlotOutput_2024_09_04" } }, "required": ["status", "data"] }, "GetReservedSlotOutput_2024_09_04": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/GetReservedSlotOutput_2024_09_04" } ] } }, "required": ["status", "data"] }, "DuplicateTeamEventTypeInput": { "type": "object", "properties": { "targetTeamId": { "type": "number", "example": 42, "description": "The team the copy is created in: the source event type's team, or another team of the same organization." }, "title": { "type": "string", "maxLength": 255, "example": "Discovery call (EMEA)" }, "slug": { "type": "string", "example": "discovery-call-emea", "description": "Must not be used by another event type in the target team." }, "description": { "type": "string", "maxLength": 3000, "description": "Defaults to the source event type's description." }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 30, "description": "Defaults to the source event type's length." } }, "required": ["targetTeamId", "title", "slug"] }, "DuplicateTeamEventTypeDataOutput": { "type": "object", "properties": { "eventType": { "description": "The new event type.", "allOf": [ { "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" } ] }, "droppedHostUserIds": { "example": [101, 102], "description": "Ids of the source's hosts and assigned users that are not accepted members of the target team, so the copy does not include them. Empty when the copy stays in the source's team.", "type": "array", "items": { "type": "number" } }, "droppedWorkflowIds": { "example": [7], "description": "Ids of the workflows active on the source that were not activated on the copy, because workflows are not carried across teams. Empty when the copy stays in the source's team.", "type": "array", "items": { "type": "number" } }, "destinationCalendarDropped": { "type": "boolean", "example": false, "description": "True when the source's destination calendar was left off the copy because the caller cannot set it, for example because the caller is not a host of the copy or the calendar is another member's connection." } }, "required": ["eventType", "droppedHostUserIds", "droppedWorkflowIds", "destinationCalendarDropped"] }, "DuplicateTeamEventTypeOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/DuplicateTeamEventTypeDataOutput" } }, "required": ["status", "data"] }, "CreateIcsFeedInputDto": { "type": "object", "properties": { "urls": { "type": "array", "minItems": 1, "example": ["https://cal.com/ics/feed.ics"], "description": "An array of ICS URLs", "items": { "type": "string", "example": "https://cal.com/ics/feed.ics" } }, "readOnly": { "type": "boolean", "default": true, "example": false, "description": "Whether to allowing writing to the calendar or not" } }, "required": ["urls"] }, "CreateIcsFeedOutput": { "type": "object", "properties": { "id": { "type": "number", "example": 1234567890, "description": "The id of the calendar credential" }, "type": { "type": "string", "example": "ics-feed_calendar", "description": "The type of the calendar" }, "userId": { "type": "integer", "nullable": true, "example": 1234567890, "description": "The user id of the user that created the calendar" }, "teamId": { "type": "integer", "nullable": true, "example": 1234567890, "description": "The team id of the user that created the calendar" }, "appId": { "type": "string", "nullable": true, "example": "ics-feed", "description": "The slug of the calendar" }, "invalid": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the calendar credentials are valid or not" } }, "required": ["id", "type", "userId", "teamId", "appId", "invalid"] }, "CreateIcsFeedOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CreateIcsFeedOutput" } }, "required": ["status", "data"] }, "BusyTimesOutput": { "type": "object", "properties": { "start": { "format": "date-time", "type": "string" }, "end": { "format": "date-time", "type": "string" }, "source": { "type": "string", "nullable": true } }, "required": ["start", "end"] }, "GetBusyTimesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusyTimesOutput" } } }, "required": ["status", "data"] }, "LocationOption": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for this location option", "example": "Google Meet" }, "value": { "type": "string", "description": "Location type identifier", "example": "integrations:google:meet" }, "icon": { "type": "string", "description": "Icon identifier for this location option" }, "disabled": { "type": "boolean", "description": "Whether this location option is disabled", "default": false } }, "required": ["label", "value"] }, "Integration": { "type": "object", "properties": { "appData": { "type": "object", "nullable": true }, "dirName": { "type": "string" }, "__template": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "installed": { "type": "boolean" }, "type": { "type": "string" }, "title": { "type": "string" }, "variant": { "type": "string" }, "category": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "logo": { "type": "string" }, "publisher": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" }, "email": { "type": "string" }, "locationOption": { "nullable": true, "description": "Location option for this integration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/LocationOption" } ] } }, "required": [ "name", "description", "type", "variant", "categories", "logo", "publisher", "slug", "url", "email", "locationOption" ] }, "Primary": { "type": "object", "properties": { "externalId": { "type": "string" }, "integration": { "type": "string" }, "name": { "type": "string" }, "primary": { "type": "boolean", "nullable": true }, "readOnly": { "type": "boolean" }, "email": { "type": "string" }, "isSelected": { "type": "boolean" }, "credentialId": { "type": "number" }, "delegationCredentialId": { "type": "string", "nullable": true } }, "required": ["externalId", "primary", "readOnly", "isSelected", "credentialId"] }, "Calendar": { "type": "object", "properties": { "externalId": { "type": "string", "format": "email" }, "integration": { "type": "string" }, "name": { "type": "string", "format": "email" }, "primary": { "type": "boolean", "nullable": true }, "readOnly": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "isSelected": { "type": "boolean" }, "credentialId": { "type": "number" }, "delegationCredentialId": { "type": "string", "nullable": true } }, "required": ["externalId", "readOnly", "isSelected", "credentialId"] }, "ConnectedCalendar": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/Integration" }, "credentialId": { "type": "number" }, "delegationCredentialId": { "type": "string", "nullable": true }, "primary": { "$ref": "#/components/schemas/Primary" }, "calendars": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } } }, "required": ["integration", "credentialId"] }, "DestinationCalendar": { "type": "object", "properties": { "id": { "type": "number" }, "integration": { "type": "string" }, "externalId": { "type": "string" }, "primaryEmail": { "type": "string", "nullable": true }, "userId": { "type": "number", "nullable": true }, "eventTypeId": { "type": "number", "nullable": true }, "credentialId": { "type": "number", "nullable": true }, "delegationCredentialId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "primary": { "type": "boolean" }, "readOnly": { "type": "boolean" }, "email": { "type": "string" }, "integrationTitle": { "type": "string" } }, "required": [ "id", "integration", "externalId", "primaryEmail", "userId", "eventTypeId", "credentialId" ] }, "ConnectedCalendarsData": { "type": "object", "properties": { "connectedCalendars": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedCalendar" } }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar" } }, "required": ["connectedCalendars", "destinationCalendar"] }, "ConnectedCalendarsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ConnectedCalendarsData" } }, "required": ["status", "data"] }, "CreateCalendarCredentialsInput": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 1 } }, "required": ["username", "password"] }, "DeleteCalendarCredentialsInputBodyDto": { "type": "object", "properties": { "id": { "type": "integer", "example": 10, "description": "Credential ID of the calendar to delete, as returned by the /calendars endpoint" } }, "required": ["id"] }, "DeletedCalendarCredentialsOutputDto": { "type": "object", "properties": { "id": { "type": "number" }, "type": { "type": "string" }, "userId": { "type": "number", "nullable": true }, "teamId": { "type": "number", "nullable": true }, "appId": { "type": "string", "nullable": true }, "invalid": { "type": "boolean", "nullable": true } }, "required": ["id", "type", "userId", "teamId", "appId", "invalid"] }, "DeletedCalendarCredentialsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DeletedCalendarCredentialsOutputDto" } }, "required": ["status", "data"] }, "ConferencingAppsOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Id of the conferencing app credentials" }, "type": { "type": "string", "example": "google_video", "description": "Type of conferencing app" }, "userId": { "type": "number", "description": "Id of the user associated to the conferencing app" }, "invalid": { "type": "boolean", "nullable": true, "example": true, "description": "Whether if the connection is working or not." } }, "required": ["id", "type", "userId"] }, "ConferencingAppOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string" }, "data": { "$ref": "#/components/schemas/ConferencingAppsOutputDto" } }, "required": ["status", "data"] }, "GetConferencingAppsOauthUrlResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] } }, "required": ["status"] }, "ConferencingAppsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConferencingAppsOutputDto" } } }, "required": ["status", "data"] }, "SetDefaultConferencingAppOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "DefaultConferencingAppsOutputDto": { "type": "object", "properties": { "appSlug": { "type": "string" }, "appLink": { "type": "string" } } }, "GetDefaultConferencingAppOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DefaultConferencingAppsOutputDto" } }, "required": ["status"] }, "DisconnectConferencingAppOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "UpdatePrivateLinkBody": { "type": "object", "properties": { "expiresAt": { "format": "date-time", "type": "string", "description": "New expiration date for time-based links", "example": "2024-12-31T23:59:59.000Z" }, "maxUsageCount": { "type": "number", "description": "New maximum number of times the link can be used. Pass `-1` to opt out of the count cap.", "example": 10 } } }, "ChargeCreditsInput": { "type": "object", "properties": { "credits": { "type": "number", "minimum": 1, "maximum": 10000, "description": "Number of credits to charge", "example": 5 }, "creditFor": { "enum": ["SMS", "CAL_AI_PHONE_CALL", "AI_AGENT"], "type": "string", "description": "What the credits are being charged for", "example": "AI_AGENT" }, "externalRef": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique external reference for idempotency", "example": "agent-thread-123-1711432800000" } }, "required": ["credits", "creditFor"] }, "MeOrgOutput": { "type": "object", "properties": { "isPlatform": { "type": "boolean" }, "id": { "type": "number" } }, "required": ["isPlatform", "id"] }, "MeOutput": { "type": "object", "properties": { "id": { "type": "number" }, "uuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "username": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "timeFormat": { "type": "number" }, "defaultScheduleId": { "type": "number", "nullable": true }, "weekStart": { "type": "string" }, "timeZone": { "type": "string" }, "locale": { "type": "string", "nullable": true, "example": "en", "description": "The user's locale setting" }, "organizationId": { "type": "number", "nullable": true }, "organization": { "$ref": "#/components/schemas/MeOrgOutput" } }, "required": [ "id", "uuid", "username", "email", "name", "avatarUrl", "bio", "timeFormat", "defaultScheduleId", "weekStart", "timeZone", "locale", "organizationId" ] }, "GetMeOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/MeOutput" } }, "required": ["status", "data"] }, "UpdateMeOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/MeOutput" } }, "required": ["status", "data"] }, "BookingLimitsOutput": { "type": "object", "properties": { "perDay": { "type": "number", "nullable": true, "example": 4 }, "perWeek": { "type": "number", "nullable": true, "example": 20 }, "perMonth": { "type": "number", "nullable": true, "example": 60 }, "perYear": { "type": "number", "nullable": true, "example": 500 } }, "required": ["perDay", "perWeek", "perMonth", "perYear"] }, "GetBookingLimitsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/BookingLimitsOutput" } }, "required": ["status", "data"] }, "UpdateBookingLimitsInput": { "type": "object", "properties": { "perDay": { "type": "number", "nullable": true, "minimum": 1, "description": "Maximum number of bookings per day. Pass null to remove this limit.", "example": 4 }, "perWeek": { "type": "number", "nullable": true, "minimum": 1, "description": "Maximum number of bookings per week. Pass null to remove this limit.", "example": 20 }, "perMonth": { "type": "number", "nullable": true, "minimum": 1, "description": "Maximum number of bookings per month. Pass null to remove this limit.", "example": 60 }, "perYear": { "type": "number", "nullable": true, "minimum": 1, "description": "Maximum number of bookings per year. Pass null to remove this limit.", "example": 500 } } }, "UpdateBookingLimitsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/BookingLimitsOutput" } }, "required": ["status", "data"] }, "CreateEventTypeInput_2026_06_12": { "type": "object", "properties": { "calendarInvites": { "description": "Write-only host and guest calendar-invite description settings. These are saved separately from the event type and are not returned by event-type read endpoints.", "example": { "host": { "mode": "custom", "template": "Meeting with {ATTENDEE}" } }, "allOf": [ { "$ref": "#/components/schemas/CalendarInvitesInput_2024_06_14" } ] }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 60 }, "lengthInMinutesOptions": { "minItems": 1, "uniqueItems": true, "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number", "minimum": 1 } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of the Argentina by making the best flan ever!" }, "slotInterval": { "type": "number", "description": "Number representing length of each slot when event is booked. By default it equal length of the event type.\n If event length is 60 minutes then we would have slots 9AM, 10AM, 11AM etc. but if it was changed to 30 minutes then\n we would have slots 9AM, 9:30AM, 10AM, 10:30AM etc. as the available times to book the 60 minute event." }, "minimumBookingNotice": { "type": "number", "minimum": 0, "description": "Minimum number of minutes before the event that a booking can be made." }, "beforeEventBuffer": { "type": "number", "description": "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." }, "afterEventBuffer": { "type": "number", "description": "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." }, "scheduleId": { "type": "number", "description": "If you want that this event has different schedule than user's default one you can specify it here." }, "bookingLimitsCount": { "description": "Limit how many times this event can be booked", "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "description": "Limit the number of active bookings a booker can make for this event type.", "oneOf": [ { "title": "Active Booking Limit", "$ref": "#/components/schemas/BookerActiveBookingsLimit_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "onlyShowFirstAvailableSlot": { "type": "boolean", "description": "This will limit your availability for this event type to one slot per day, scheduled at the earliest available time." }, "bookingLimitsDuration": { "description": "Limit total amount of time that this event can be booked", "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "description": "Limit how far in the future this event can be booked", "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "offsetStart": { "type": "number", "minimum": 0, "description": "Offset timeslots shown to bookers by a specified number of minutes" }, "bookerLayouts": { "description": "Should booker have week, month or column view. Specify default layout and enabled layouts user can pick.", "allOf": [ { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" } ] }, "confirmationPolicy": { "description": "Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.", "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "recurrence": { "description": "Create a recurring event type.", "oneOf": [ { "title": "Recurring Event", "$ref": "#/components/schemas/Recurrence_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, skips the MX deliverability check for attendee emails on booking. Format validation and watchlist still apply. Requires the editor to belong to an organization (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "description": "Create an event type with multiple seats.", "oneOf": [ { "title": "Seated Event", "$ref": "#/components/schemas/Seats_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "customName": { "type": "string", "description": "Customizable event name with valid variables:\n {Link title}, {Event type title} (legacy), {Organiser}, {Scheduler}, {Location}, {Organiser first name},\n {Scheduler first name}, {Scheduler last name}, {Event duration}, {LOCATION},\n {HOST/ATTENDEE}, {HOST}, {ATTENDEE}, {USER}", "example": "{Link title} between {Organiser} and {Scheduler}" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "successRedirectUrl": { "type": "string", "format": "uri", "description": "A valid URL where the booker will redirect to, once the booking is completed successfully", "example": "https://masterchief.com/argentina/flan/video/9129412" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "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.", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "default": false, "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "example": { "disabled": true }, "allOf": [ { "$ref": "#/components/schemas/DisableCancelling_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "example": { "disabled": false, "minutesBefore": 60 }, "allOf": [ { "$ref": "#/components/schemas/DisableRescheduling_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "description": "Set preferred language for the booking interface. Use empty string for visitor's browser language (default).", "enum": [ "", "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", "sl", "sr", "sv", "tr", "uk", "vi", "zh-CN", "zh-TW" ] }, "weekStart": { "nullable": true, "enum": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], "type": "string", "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only. Omit or set to null to inherit the account setting.", "example": "Monday" }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled.", "default": false }, "allowReschedulingCancelledBookings": { "type": "boolean", "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking.", "default": false }, "showOptimizedSlots": { "type": "boolean", "description": "Arrange time slots to optimize availability.", "default": false }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members.", "default": false }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host.", "default": false }, "privateNoteMode": { "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "example": "duplicate_event", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names.", "example": "Meeting with {Attendee name} for {Link title}" }, "locations": { "type": "array", "description": "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 Cal.com 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.", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/InputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/InputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/InputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/InputPhoneLocation_2024_06_14" }, { "title": "Attendee Address", "$ref": "#/components/schemas/InputAttendeeAddressLocation_2024_06_14" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/InputAttendeePhoneLocation_2024_06_14" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/InputAttendeeDefinedLocation_2024_06_14" } ] } }, "bookingFields": { "type": "array", "description": "Booking fields for the event type. Omit this property to use the default fields. Provide an array to customize default fields or add custom booking fields. At least one of `email` or `attendeePhoneNumber` must be visible and required. The array cannot be empty, contain duplicate default fields or custom slugs, or use a default field's slug for a custom field. Omitted default fields are added with their default settings. Workflow-added fields are read-only and ignored.", "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] } }, "crm": { "description": "CRM app settings for the event type, mirroring the event type Apps tab toggles. The credential is resolved server-side — the app must be installed for the event type owner.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsInput_2026_06_12" } ] } }, "required": ["lengthInMinutes", "title", "slug"] }, "User_2024_06_14": { "type": "object", "properties": { "id": { "type": "number" }, "uuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "name": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "weekStart": { "type": "string" }, "brandColor": { "type": "string", "nullable": true }, "darkBrandColor": { "type": "string", "nullable": true }, "metadata": { "type": "object" } }, "required": [ "id", "uuid", "name", "username", "avatarUrl", "weekStart", "brandColor", "darkBrandColor", "metadata" ] }, "EventTypeOutput_2026_06_12": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "lengthInMinutes": { "type": "number", "example": 60 }, "lengthInMinutesOptions": { "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number" } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of Argentina by making the best flan ever!" }, "locations": { "type": "array", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/OutputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/OutputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/OutputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/OutputPhoneLocation_2024_06_14" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/OutputOrganizersDefaultAppLocation_2024_06_14" }, { "title": "Unknown", "$ref": "#/components/schemas/OutputUnknownLocation_2024_06_14" } ] } }, "disableGuests": { "type": "boolean" }, "slotInterval": { "type": "number", "example": 60, "nullable": true }, "minimumBookingNotice": { "type": "number", "example": 0 }, "beforeEventBuffer": { "type": "number", "example": 0 }, "afterEventBuffer": { "type": "number", "example": 0 }, "recurrence": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/Recurrence_2024_06_14" } ] }, "metadata": { "type": "object", "readOnly": true }, "price": { "type": "number" }, "currency": { "type": "string" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "seatsPerTimeSlot": { "type": "number", "nullable": true }, "forwardParamsSuccessRedirect": { "type": "boolean", "nullable": true }, "successRedirectUrl": { "type": "string", "nullable": true }, "isInstantEvent": { "type": "boolean" }, "seatsShowAvailabilityCount": { "type": "boolean", "nullable": true }, "scheduleId": { "type": "number", "nullable": true }, "bookingLimitsCount": { "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "$ref": "#/components/schemas/BookerActiveBookingsLimitOutput_2024_06_14" }, "onlyShowFirstAvailableSlot": { "type": "boolean" }, "bookingLimitsDuration": { "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "type": "array", "description": "Limit how far in the future this event can be booked", "items": { "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" } ] } }, "bookerLayouts": { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" }, "confirmationPolicy": { "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingProposalCount": { "type": "number", "nullable": true, "description": "Maximum number of timeslots a proposal may include. The client chooses from 1 through this maximum. Null uses the default single-slot booking flow." }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, the MX deliverability check for attendee emails is skipped on booking. Format validation and watchlist still apply. Org-only (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "$ref": "#/components/schemas/Seats_2024_06_14" }, "offsetStart": { "type": "number" }, "customName": { "type": "string" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "Cal video settings for the event type", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "allOf": [ { "$ref": "#/components/schemas/DisableCancellingOutput_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "allOf": [ { "$ref": "#/components/schemas/DisableReschedulingOutput_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "nullable": true, "description": "Set preferred language for the booking interface." }, "weekStart": { "type": "string", "nullable": true, "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only." }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled." }, "allowReschedulingCancelledBookings": { "type": "boolean", "nullable": true, "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking." }, "showOptimizedSlots": { "type": "boolean", "nullable": true, "description": "Arrange time slots to optimize availability." }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members." }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host." }, "privateNoteMode": { "nullable": true, "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "nullable": true, "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names." }, "ownerId": { "type": "number", "example": 10 }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/User_2024_06_14" } }, "bookingUrl": { "type": "string", "description": "Full URL to the booking page for this event type", "example": "https://cal.com/john-doe/30min", "format": "uri" }, "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "The event type's booking fields — the default ones, any custom ones, and any added automatically by an attached workflow." }, "crm": { "description": "CRM app settings configured for this event type, mirroring the event type Apps tab toggles.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsOutput_2026_06_12" } ] } }, "required": [ "id", "lengthInMinutes", "title", "slug", "description", "locations", "disableGuests", "recurrence", "metadata", "price", "currency", "lockTimeZoneToggleOnBookingPage", "forwardParamsSuccessRedirect", "successRedirectUrl", "isInstantEvent", "scheduleId", "hidden", "bookingRequiresAuthentication", "ownerId", "users", "bookingUrl", "bookingFields", "crm" ] }, "CreateEventTypeOutput_2026_06_12": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventTypeOutput_2026_06_12" } }, "required": ["status", "data"] }, "RawValueFieldValue_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["rawValue"], "description": "Discriminator indicating this field holds a single plain-text value." }, "value": { "type": "string", "example": "enabled", "description": "The plain-text value of the field." } }, "required": ["type", "value"] }, "RawValuesFieldValue_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["rawValues"], "description": "Discriminator indicating this field holds a list of plain-text values." }, "values": { "example": ["Google Meet", "Cal Video"], "description": "List of plain-text values.", "type": "array", "items": { "type": "string" } } }, "required": ["type", "values"] }, "ValueChangeFieldValue_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["valueChange"], "description": "Discriminator indicating a primitive value changed from one value to another." }, "previous": { "type": "string", "example": "30", "description": "The value before the change." }, "next": { "type": "string", "example": "60", "description": "The value after the change." } }, "required": ["type", "previous", "next"] }, "DiffFieldValue_2024_06_14": { "type": "object", "properties": { "type": { "type": "string", "enum": ["diff"], "description": "Discriminator indicating this field contains a JSON diff of complex (object/array) values." }, "previous": { "type": "string", "example": "{\"key\": \"old\"}", "description": "JSON-stringified previous value." }, "next": { "type": "string", "example": "{\"key\": \"new\"}", "description": "JSON-stringified new value." } }, "required": ["type", "previous", "next"] }, "EventTypeHistoryActor_2024_06_14": { "type": "object", "properties": { "type": { "enum": ["USER", "GUEST", "ATTENDEE", "SYSTEM", "APP"], "type": "string", "example": "USER", "description": "The type of actor who performed the action." }, "displayName": { "type": "string", "nullable": true, "example": "Ada Lovelace", "description": "Display name of the actor, or null if unavailable." }, "displayEmail": { "type": "string", "nullable": true, "example": "ada@example.com", "description": "Email address of the actor, or null if unavailable." }, "displayAvatar": { "type": "string", "nullable": true, "example": "https://example.com/avatar.png", "description": "Avatar URL of the actor, or null if unavailable." } }, "required": ["type", "displayName", "displayEmail", "displayAvatar"] }, "EventTypeHistoryImpersonatedBy_2024_06_14": { "type": "object", "properties": { "displayName": { "type": "string", "example": "Grace Hopper", "description": "Display name of the user who was being impersonated." }, "displayEmail": { "type": "string", "nullable": true, "example": "grace@example.com", "description": "Email address of the impersonated user, or null if unavailable." }, "displayAvatar": { "type": "string", "nullable": true, "example": "https://example.com/avatar.png", "description": "Avatar URL of the impersonated user, or null if unavailable." } }, "required": ["displayName", "displayEmail", "displayAvatar"] }, "EventTypeHistoryDisplayField_2024_06_14": { "type": "object", "properties": { "label": { "type": "string", "example": "Duration", "description": "Human-readable English label for the changed field." }, "fieldValue": { "oneOf": [ { "title": "Raw Value", "$ref": "#/components/schemas/RawValueFieldValue_2024_06_14" }, { "title": "Raw Values", "$ref": "#/components/schemas/RawValuesFieldValue_2024_06_14" }, { "title": "Value Change", "$ref": "#/components/schemas/ValueChangeFieldValue_2024_06_14" }, { "title": "Difference", "$ref": "#/components/schemas/DiffFieldValue_2024_06_14" } ], "discriminator": { "propertyName": "type", "mapping": { "rawValue": "#/components/schemas/RawValueFieldValue_2024_06_14", "rawValues": "#/components/schemas/RawValuesFieldValue_2024_06_14", "valueChange": "#/components/schemas/ValueChangeFieldValue_2024_06_14", "diff": "#/components/schemas/DiffFieldValue_2024_06_14" } }, "description": "The field value, discriminated by `type`. Each variant includes only its relevant required fields." } }, "required": ["label", "fieldValue"] }, "EventTypeHistoryAuditLog_2024_06_14": { "type": "object", "properties": { "id": { "type": "string", "example": "018f4c2e-3f1a-7abc-9def-0123456789ab", "description": "Unique identifier of the audit log entry." }, "action": { "enum": ["EVENT_TYPE_MODIFIED", "EVENT_TYPE_CREATED", "EVENT_TYPE_DELETED"], "type": "string", "example": "EVENT_TYPE_MODIFIED", "description": "The type of change that was made to the event type." }, "type": { "type": "string", "example": "RECORD_MODIFIED", "description": "The category of audit record." }, "timestamp": { "type": "string", "example": "2026-01-01T00:00:00.000Z", "description": "ISO 8601 timestamp of when the change occurred." }, "source": { "type": "string", "example": "WEBAPP", "description": "The source application or context where the change was made." }, "actor": { "description": "The user or system that performed the change.", "allOf": [ { "$ref": "#/components/schemas/EventTypeHistoryActor_2024_06_14" } ] }, "impersonatedBy": { "nullable": true, "description": "Present when the action was performed via user impersonation. Contains details of the impersonated user.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventTypeHistoryImpersonatedBy_2024_06_14" } ] }, "actionDisplayTitle": { "type": "string", "example": "Ada Lovelace modified the event type", "description": "Human-readable English summary of who performed the action." }, "displayFields": { "description": "List of fields that were changed, with their old and new values.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeHistoryDisplayField_2024_06_14" } }, "displayJson": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Raw JSON representation of the full change payload, or null if unavailable." }, "hasError": { "type": "boolean", "example": false, "description": "Whether an error occurred while parsing the audit log entry." } }, "required": [ "id", "action", "type", "timestamp", "source", "actor", "actionDisplayTitle", "displayFields", "displayJson" ] }, "EventTypeHistoryData_2024_06_14": { "type": "object", "properties": { "eventTypeId": { "type": "number", "example": 123, "description": "The ID of the event type whose history is being returned." }, "auditLogs": { "description": "List of audit log entries for the event type, ordered by most recent first.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeHistoryAuditLog_2024_06_14" } } }, "required": ["eventTypeId", "auditLogs"] }, "EventTypeHistoryPagination_2024_06_14": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor to fetch the next page. Pass this value as the `cursor` query parameter on the next request. `null` when `hasMore` is `false`.", "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJpZCI6IjAxSFgifQ" }, "hasMore": { "type": "boolean", "description": "Whether more pages are available after this one.", "example": false } }, "required": ["nextCursor", "hasMore"] }, "GetEventTypeHistoryOutput_2024_06_14": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success", "description": "Indicates whether the request was successful." }, "data": { "description": "The event type history data including audit log entries.", "allOf": [ { "$ref": "#/components/schemas/EventTypeHistoryData_2024_06_14" } ] }, "pagination": { "description": "Pagination metadata for fetching additional pages.", "allOf": [ { "$ref": "#/components/schemas/EventTypeHistoryPagination_2024_06_14" } ] } }, "required": ["status", "data", "pagination"] }, "SchedulingHost": { "type": "object", "properties": { "userId": { "type": "number", "example": 1, "description": "User ID of the host" }, "name": { "type": "string", "example": "John Doe", "description": "Display name of the host" }, "username": { "type": "string", "example": "john-doe", "description": "Username of the host" }, "mandatory": { "type": "boolean", "example": false, "description": "If true, this host is a fixed host who always attends (not in the round-robin rotation pool)" }, "priority": { "nullable": true, "enum": ["lowest", "low", "medium", "high", "highest"], "type": "string", "example": "medium", "description": "Priority level for round-robin distribution. Only present for roundRobin scheduling type." }, "weight": { "type": "number", "nullable": true, "example": 100, "description": "Weight for round-robin distribution. Higher weight means more bookings assigned. Only present for roundRobin scheduling type." }, "avatarUrl": { "type": "string", "nullable": true }, "groupId": { "type": "string", "nullable": true, "description": "ID of the host group this host belongs to. Only present for roundRobin scheduling type." } }, "required": ["userId", "name", "username", "mandatory"] }, "SchedulingHostGroup": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the host group" }, "name": { "type": "string", "example": "Sales Team", "description": "Name of the host group" } }, "required": ["id", "name"] }, "SchedulingConfigData": { "type": "object", "properties": { "eventTypeId": { "type": "number", "example": 1, "description": "Event type ID" }, "schedulingType": { "type": "string", "enum": ["roundRobin", "collective", "managed"], "example": "roundRobin", "description": "The scheduling type of this event type. Determines which fields are populated." }, "hosts": { "description": "Array of hosts assigned to this event type", "type": "array", "items": { "$ref": "#/components/schemas/SchedulingHost" } }, "assignAllTeamMembers": { "type": "boolean", "example": false, "description": "Whether all team members are automatically assigned as hosts" }, "hostGroups": { "description": "Host groups for organizing round-robin hosts. Only present for roundRobin scheduling type.", "type": "array", "items": { "$ref": "#/components/schemas/SchedulingHostGroup" } }, "rescheduleWithSameRoundRobinHost": { "type": "boolean", "example": false, "description": "Whether rescheduled events keep the same round-robin host. Only present for roundRobin scheduling type." }, "allowRRHostChoiceOnReschedule": { "type": "boolean", "example": false, "description": "Whether the person rescheduling may choose between the original host and the whole team. Only present for roundRobin scheduling type." }, "isRRWeightsEnabled": { "type": "boolean", "example": false, "description": "Whether round-robin weights are enabled for host distribution. Only present for roundRobin scheduling type." }, "maxLeadThreshold": { "type": "number", "nullable": true, "example": 3, "description": "Max lead threshold for load-balanced distribution. null = 'maximize availability', number = 'load balancing'. Only present for roundRobin scheduling type." }, "includeNoShowInRRCalculation": { "type": "boolean", "example": false, "description": "Whether no-show bookings are included in round-robin calculations. Only present for roundRobin scheduling type." }, "crmRecordOwnerFallbackWindowHours": { "type": "number", "nullable": true, "example": 24, "description": "CRM record owner fallback window in hours. Only present for roundRobin scheduling type." }, "crmRecordOwnerFallbackWindowSkipWeekends": { "type": "boolean", "example": false, "description": "Whether to exclude weekends from the CRM record owner fallback window calculation. Only present for roundRobin scheduling type." } }, "required": ["eventTypeId", "schedulingType", "hosts", "assignAllTeamMembers"] }, "GetSchedulingConfigOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SchedulingConfigData" } }, "required": ["status", "data"] }, "CrmSyncErrorOutput_2024_06_14": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique CRM sync error ID.", "example": "019ea850-efc7-7a48-8508-aed31b72ce68" }, "credentialId": { "type": "number", "description": "Credential ID that produced the CRM sync error.", "example": 123 }, "eventTypeId": { "type": "number", "description": "Event type ID where the CRM sync error occurred.", "example": 49 }, "appSlug": { "type": "string", "description": "CRM app slug that produced the error.", "example": "salesforce" }, "timestamp": { "type": "string", "description": "Timestamp when the CRM sync error was recorded.", "example": "2026-06-08T17:38:57.107Z" }, "errorCode": { "type": "string", "description": "Provider-specific CRM error code.", "example": "FIELD_CUSTOM_VALIDATION_EXCEPTION" }, "errorMessage": { "type": "string", "description": "Human-readable CRM error message.", "example": "Validation rule blocked this update" }, "rawMessage": { "type": "string", "description": "Raw provider error message, when available.", "example": "FIELD_CUSTOM_VALIDATION_EXCEPTION: Validation rule blocked this update" }, "droppedFields": { "description": "CRM fields dropped or attempted during sync error handling.", "example": ["Custom_Field__c"], "type": "array", "items": { "type": "string" } }, "eventCreated": { "type": "boolean", "nullable": true, "description": "Whether the CRM event was created before the error was recorded.", "example": false }, "bookingUid": { "type": "string", "description": "Booking UID associated with the CRM sync error, when available.", "example": "booking_uid_123" }, "dismissedAt": { "type": "string", "nullable": true, "description": "Timestamp when the CRM sync error was dismissed. Null means the error is active.", "example": "2026-06-08T17:40:00.000Z" } }, "required": [ "id", "credentialId", "eventTypeId", "appSlug", "timestamp", "errorCode", "errorMessage", "droppedFields", "dismissedAt" ] }, "CrmSyncErrorsPaginationOutput_2024_06_14": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when no more rows are available.", "example": "eyJ2IjoxLCJzb3J0VXVpZCI6IjAxOWVhODUwLWVmYzctN2E0OC04NTA4LWFlZDMxYjcyY2U2OCJ9" }, "hasMore": { "type": "boolean", "description": "Whether more CRM sync error rows are available.", "example": true } }, "required": ["nextCursor", "hasMore"] }, "GetCrmSyncErrorsOutput_2024_06_14": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "description": "CRM sync errors scoped to the requested event type and connected CRM app.", "type": "array", "items": { "$ref": "#/components/schemas/CrmSyncErrorOutput_2024_06_14" } }, "pagination": { "$ref": "#/components/schemas/CrmSyncErrorsPaginationOutput_2024_06_14" } }, "required": ["status", "data", "pagination"] }, "GetEventTypeOutput_2026_06_12": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Event Type", "$ref": "#/components/schemas/EventTypeOutput_2026_06_12" }, { "title": "Team Event Type", "$ref": "#/components/schemas/TeamEventTypeOutput_2026_06_12" } ] } }, "required": ["status", "data"] }, "GetEventTypesOutput_2026_06_12": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeOutput_2026_06_12" } } }, "required": ["status", "data"] }, "UpdateEventTypeInput_2026_06_12": { "type": "object", "properties": { "calendarInvites": { "description": "Write-only host and guest calendar-invite description settings. These are saved separately from the event type and are not returned by event-type read endpoints.", "example": { "guest": { "mode": "custom", "template": "Meeting with {ATTENDEE}" } }, "allOf": [ { "$ref": "#/components/schemas/CalendarInvitesInput_2024_06_14" } ] }, "lengthInMinutes": { "type": "number", "example": 60 }, "lengthInMinutesOptions": { "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number" } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of the Argentina by making the best flan ever!" }, "slotInterval": { "type": "number", "description": "Number representing length of each slot when event is booked. By default it equal length of the event type.\n If event length is 60 minutes then we would have slots 9AM, 10AM, 11AM etc. but if it was changed to 30 minutes then\n we would have slots 9AM, 9:30AM, 10AM, 10:30AM etc. as the available times to book the 60 minute event." }, "minimumBookingNotice": { "type": "number", "description": "Minimum number of minutes before the event that a booking can be made." }, "beforeEventBuffer": { "type": "number", "description": "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." }, "afterEventBuffer": { "type": "number", "description": "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." }, "scheduleId": { "type": "number", "description": "If you want that this event has different schedule than user's default one you can specify it here." }, "bookingLimitsCount": { "description": "Limit how many times this event can be booked", "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "description": "Limit the number of active bookings a booker can make for this event type.", "oneOf": [ { "title": "Active Booking Limit", "$ref": "#/components/schemas/BookerActiveBookingsLimit_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "onlyShowFirstAvailableSlot": { "type": "boolean", "description": "This will limit your availability for this event type to one slot per day, scheduled at the earliest available time." }, "bookingLimitsDuration": { "description": "Limit total amount of time that this event can be booked", "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "description": "Limit how far in the future this event can be booked", "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "offsetStart": { "type": "number", "description": "Offset timeslots shown to bookers by a specified number of minutes" }, "bookerLayouts": { "description": "Should booker have week, month or column view. Specify default layout and enabled layouts user can pick.", "allOf": [ { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" } ] }, "confirmationPolicy": { "description": "Specify how the booking needs to be manually confirmed before it is pushed to the integrations and a confirmation mail is sent.", "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingProposalCount": { "type": "number", "nullable": true, "description": "Maximum number of timeslots a proposal may include. The client chooses from 1 through this maximum. Set to null to use the default single-slot booking flow." }, "recurrence": { "description": "Create a recurring event type.", "oneOf": [ { "title": "Recurring Event", "$ref": "#/components/schemas/Recurrence_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, skips the MX deliverability check for attendee emails on booking. Format validation and watchlist still apply. Requires the editor to belong to an organization (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "description": "Create an event type with multiple seats.", "oneOf": [ { "title": "Seated Event", "$ref": "#/components/schemas/Seats_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "customName": { "type": "string", "description": "Customizable event name with valid variables:\n {Link title}, {Event type title} (legacy), {Organiser}, {Scheduler}, {Location}, {Organiser first name},\n {Scheduler first name}, {Scheduler last name}, {Event duration}, {LOCATION},\n {HOST/ATTENDEE}, {HOST}, {ATTENDEE}, {USER}", "example": "{Link title} between {Organiser} and {Scheduler}" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "successRedirectUrl": { "type": "string", "description": "A valid URL where the booker will redirect to, once the booking is completed successfully", "example": "https://masterchief.com/argentina/flan/video/9129412" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "Cal video settings for the event type", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "default": false, "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "example": { "disabled": true }, "allOf": [ { "$ref": "#/components/schemas/DisableCancelling_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "example": { "disabled": false, "minutesBefore": 60 }, "allOf": [ { "$ref": "#/components/schemas/DisableRescheduling_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "description": "Set preferred language for the booking interface. Use empty string for visitor's browser language (default).", "enum": [ "", "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", "sl", "sr", "sv", "tr", "uk", "vi", "zh-CN", "zh-TW" ] }, "weekStart": { "type": "string", "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only. Omit or set to null to inherit the account setting.", "enum": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], "example": "Monday" }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled.", "default": false }, "allowReschedulingCancelledBookings": { "type": "boolean", "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking.", "default": false }, "showOptimizedSlots": { "type": "boolean", "description": "Arrange time slots to optimize availability.", "default": false }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members.", "default": false }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host.", "default": false }, "privateNoteMode": { "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "example": "duplicate_event", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names.", "example": "Meeting with {Attendee name} for {Link title}" }, "allowAffectingUpcomingBookings": { "type": "boolean", "description": "Allows this update to affect upcoming bookings when a live confirmation session exists. Not stored and not returned. `true` confirms the edit:\n- Turning seats off cancels every attendee and booking attempt, and new bookings are taken one at a time.\n- Turning confirmation off rejects pending requests, leaves accepted attendees, and confirms new booking attempts until the seats are full.\n- Setting the seat cap below the seats already accepted keeps existing bookings and their seats, and applies the lower cap to new bookings and later confirmations.\n`false` and omitting the field leave the update refused when it would affect upcoming bookings." }, "locations": { "type": "array", "description": "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 Cal.com 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.", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/InputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/InputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/InputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/InputPhoneLocation_2024_06_14" }, { "title": "Attendee Address", "$ref": "#/components/schemas/InputAttendeeAddressLocation_2024_06_14" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/InputAttendeePhoneLocation_2024_06_14" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/InputAttendeeDefinedLocation_2024_06_14" } ] } }, "bookingFields": { "type": "array", "description": "Booking fields for the event type. Omit this property to keep the current fields. Provide an array to replace them, customize default fields, or add custom booking fields. At least one of `email` or `attendeePhoneNumber` must be visible and required. The array cannot be empty, contain duplicate default fields or custom slugs, or use a default field's slug for a custom field. Omitted default fields are restored with their default settings. Workflow-added fields are read-only and ignored.", "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] } }, "crm": { "description": "CRM app settings for the event type, mirroring the event type Apps tab toggles. The credential is resolved server-side — the app must be installed for the event type owner.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsInput_2026_06_12" } ] } } }, "UpdateEventTypeOutput_2026_06_12": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventTypeOutput_2026_06_12" } }, "required": ["status", "data"] }, "DeleteData_2024_06_14": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "lengthInMinutes": { "type": "number", "example": 60 }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string" } }, "required": ["id", "lengthInMinutes", "title", "slug"] }, "DeleteEventTypeOutput_2024_06_14": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DeleteData_2024_06_14" } }, "required": ["status", "data"] }, "LinkOutput": { "type": "object", "properties": { "lengthInMinutes": { "type": "number", "example": 60 }, "lengthInMinutesOptions": { "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number" } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of Argentina by making the best flan ever!" }, "locations": { "type": "array", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/OutputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/OutputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/OutputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/OutputPhoneLocation_2024_06_14" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/OutputOrganizersDefaultAppLocation_2024_06_14" }, { "title": "Unknown", "$ref": "#/components/schemas/OutputUnknownLocation_2024_06_14" } ] } }, "disableGuests": { "type": "boolean" }, "slotInterval": { "type": "number", "example": 60, "nullable": true }, "minimumBookingNotice": { "type": "number", "example": 0 }, "beforeEventBuffer": { "type": "number", "example": 0 }, "afterEventBuffer": { "type": "number", "example": 0 }, "recurrence": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/Recurrence_2024_06_14" } ] }, "metadata": { "type": "object", "readOnly": true }, "price": { "type": "number" }, "currency": { "type": "string" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "seatsPerTimeSlot": { "type": "number", "nullable": true }, "forwardParamsSuccessRedirect": { "type": "boolean", "nullable": true }, "successRedirectUrl": { "type": "string", "nullable": true }, "isInstantEvent": { "type": "boolean" }, "seatsShowAvailabilityCount": { "type": "boolean", "nullable": true }, "scheduleId": { "type": "number", "nullable": true }, "bookingLimitsCount": { "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "$ref": "#/components/schemas/BookerActiveBookingsLimitOutput_2024_06_14" }, "onlyShowFirstAvailableSlot": { "type": "boolean" }, "bookingLimitsDuration": { "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "type": "array", "description": "Limit how far in the future this event can be booked", "items": { "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" } ] } }, "bookerLayouts": { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" }, "confirmationPolicy": { "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingProposalCount": { "type": "number", "nullable": true, "description": "Maximum number of timeslots a proposal may include. The client chooses from 1 through this maximum. Null uses the default single-slot booking flow." }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, the MX deliverability check for attendee emails is skipped on booking. Format validation and watchlist still apply. Org-only (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "$ref": "#/components/schemas/Seats_2024_06_14" }, "offsetStart": { "type": "number" }, "customName": { "type": "string" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "Cal video settings for the event type", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "allOf": [ { "$ref": "#/components/schemas/DisableCancellingOutput_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "allOf": [ { "$ref": "#/components/schemas/DisableReschedulingOutput_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "nullable": true, "description": "Set preferred language for the booking interface." }, "weekStart": { "type": "string", "nullable": true, "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only." }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled." }, "allowReschedulingCancelledBookings": { "type": "boolean", "nullable": true, "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking." }, "showOptimizedSlots": { "type": "boolean", "nullable": true, "description": "Arrange time slots to optimize availability." }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members." }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host." }, "privateNoteMode": { "nullable": true, "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "nullable": true, "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names." }, "ownerId": { "type": "number", "example": 10 }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/User_2024_06_14" } }, "bookingUrl": { "type": "string", "description": "Full URL to the booking page for this event type", "example": "https://cal.com/john-doe/30min", "format": "uri" }, "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "The event type's booking fields — the default ones, any custom ones, and any added automatically by an attached workflow." }, "crm": { "description": "CRM app settings configured for this event type, mirroring the event type Apps tab toggles.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsOutput_2026_06_12" } ] }, "uuid": { "type": "string", "format": "uuid", "example": "018ff5cd-6dc4-7d57-bcbc-374702ca8b38" }, "parentLinkUid": { "type": "string", "nullable": true, "format": "uuid", "description": "The uuid of the managed parent link this link was created from." } }, "required": [ "lengthInMinutes", "title", "slug", "description", "locations", "disableGuests", "recurrence", "metadata", "price", "currency", "lockTimeZoneToggleOnBookingPage", "forwardParamsSuccessRedirect", "successRedirectUrl", "isInstantEvent", "scheduleId", "hidden", "bookingRequiresAuthentication", "ownerId", "users", "bookingUrl", "bookingFields", "crm", "uuid", "parentLinkUid" ] }, "TeamLinkOutput": { "type": "object", "properties": { "lengthInMinutes": { "type": "number", "example": 60 }, "lengthInMinutesOptions": { "example": [15, 30, 60], "description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.", "type": "array", "items": { "type": "number" } }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "slug": { "type": "string", "example": "learn-the-secrets-of-masterchief" }, "description": { "type": "string", "example": "Discover the culinary wonders of Argentina by making the best flan ever!" }, "locations": { "type": "array", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/OutputAddressLocation_2024_06_14" }, { "title": "Link", "$ref": "#/components/schemas/OutputLinkLocation_2024_06_14" }, { "title": "Integration", "$ref": "#/components/schemas/OutputIntegrationLocation_2024_06_14" }, { "title": "Phone", "$ref": "#/components/schemas/OutputPhoneLocation_2024_06_14" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/OutputOrganizersDefaultAppLocation_2024_06_14" }, { "title": "Unknown", "$ref": "#/components/schemas/OutputUnknownLocation_2024_06_14" } ] } }, "disableGuests": { "type": "boolean" }, "slotInterval": { "type": "number", "example": 60, "nullable": true }, "minimumBookingNotice": { "type": "number", "example": 0 }, "beforeEventBuffer": { "type": "number", "example": 0 }, "afterEventBuffer": { "type": "number", "example": 0 }, "recurrence": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/Recurrence_2024_06_14" } ] }, "metadata": { "type": "object", "readOnly": true }, "price": { "type": "number" }, "currency": { "type": "string" }, "lockTimeZoneToggleOnBookingPage": { "type": "boolean" }, "seatsPerTimeSlot": { "type": "number", "nullable": true }, "forwardParamsSuccessRedirect": { "type": "boolean", "nullable": true }, "successRedirectUrl": { "type": "string", "nullable": true }, "isInstantEvent": { "type": "boolean" }, "seatsShowAvailabilityCount": { "type": "boolean", "nullable": true }, "scheduleId": { "type": "number", "nullable": true }, "bookingLimitsCount": { "oneOf": [ { "title": "Booking Count Limit", "$ref": "#/components/schemas/BaseBookingLimitsCount_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookerActiveBookingsLimit": { "$ref": "#/components/schemas/BookerActiveBookingsLimitOutput_2024_06_14" }, "onlyShowFirstAvailableSlot": { "type": "boolean" }, "bookingLimitsDuration": { "oneOf": [ { "title": "Booking Duration Limit", "$ref": "#/components/schemas/BaseBookingLimitsDuration_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingWindow": { "type": "array", "description": "Limit how far in the future this event can be booked", "items": { "oneOf": [ { "title": "Business Days", "$ref": "#/components/schemas/BusinessDaysWindow_2024_06_14" }, { "title": "Calendar Days", "$ref": "#/components/schemas/CalendarDaysWindow_2024_06_14" }, { "title": "Date Range", "$ref": "#/components/schemas/RangeWindow_2024_06_14" } ] } }, "bookerLayouts": { "$ref": "#/components/schemas/BookerLayouts_2024_06_14" }, "confirmationPolicy": { "oneOf": [ { "title": "Confirmation Required", "$ref": "#/components/schemas/BaseConfirmationPolicy_2024_06_14" }, { "title": "Disabled", "$ref": "#/components/schemas/Disabled_2024_06_14" } ] }, "bookingProposalCount": { "type": "number", "nullable": true, "description": "Maximum number of timeslots a proposal may include. The client chooses from 1 through this maximum. Null uses the default single-slot booking flow." }, "requiresBookerEmailVerification": { "type": "boolean" }, "skipAttendeeEmailDeliverabilityCheck": { "type": "boolean", "description": "When true, the MX deliverability check for attendee emails is skipped on booking. Format validation and watchlist still apply. Org-only (including platform orgs)." }, "emailSettings": { "description": "Email settings for this event type. Personal event types require an accepted organization membership; team event types require an organization team. This does not include emails sent by custom email workflows.", "allOf": [ { "$ref": "#/components/schemas/EmailSettings_2024_06_14" } ] }, "hideCalendarNotes": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/EventTypeColor_2024_06_14" }, "seats": { "$ref": "#/components/schemas/Seats_2024_06_14" }, "offsetStart": { "type": "number" }, "customName": { "type": "string" }, "destinationCalendar": { "$ref": "#/components/schemas/DestinationCalendar_2024_06_14" }, "useDestinationCalendarEmail": { "type": "boolean" }, "hideCalendarEventDetails": { "type": "boolean" }, "hideOrganizerEmail": { "type": "boolean", "description": "Boolean to Hide organizer's email address from the booking screen, email notifications, and calendar events" }, "calVideoSettings": { "description": "Cal video settings for the event type", "allOf": [ { "$ref": "#/components/schemas/CalVideoSettings" } ] }, "hidden": { "type": "boolean" }, "bookingRequiresAuthentication": { "type": "boolean", "description": "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." }, "disableCancelling": { "description": "Settings for disabling cancelling of this event type.", "allOf": [ { "$ref": "#/components/schemas/DisableCancellingOutput_2024_06_14" } ] }, "disableRescheduling": { "description": "Settings for disabling rescheduling of this event type. Can be always disabled or disabled when less than X minutes before the meeting.", "allOf": [ { "$ref": "#/components/schemas/DisableReschedulingOutput_2024_06_14" } ] }, "interfaceLanguage": { "type": "string", "nullable": true, "description": "Set preferred language for the booking interface." }, "weekStart": { "type": "string", "nullable": true, "description": "Day the booking page calendar starts the week on. Overrides the host's account setting for this event type only." }, "allowReschedulingPastBookings": { "type": "boolean", "description": "Enabling this option allows for past events to be rescheduled." }, "allowReschedulingCancelledBookings": { "type": "boolean", "nullable": true, "description": "When enabled, users will be able to create a new booking when trying to reschedule a cancelled booking." }, "showOptimizedSlots": { "type": "boolean", "nullable": true, "description": "Arrange time slots to optimize availability." }, "useIsolatedAvailability": { "type": "boolean", "description": "When true, only this event type's own Cal.com bookings block the slot. The availability schedule and connected calendars still apply. Same as \"Consider only this booking link's bookings\" in the web app. Requires an organization with at least 15 members." }, "privateNoteEnabled": { "type": "boolean", "description": "When enabled, a private note calendar event is created alongside the booking with the resolved template as its description. Only visible to the host." }, "privateNoteMode": { "nullable": true, "description": "How private notes are delivered: as an additional host event or by sending separate host and guest invites.", "allOf": [ { "$ref": "#/components/schemas/PrivateNoteMode" } ] }, "privateNoteTemplate": { "type": "string", "nullable": true, "description": "Template for the private note content. Supports variables like {Attendee name}, {Link title}, {Event type title} (legacy), {Location}, {Host name}, {Event duration}, and custom booking field names." }, "teamId": { "type": "number" }, "bookingUrl": { "type": "string", "nullable": true, "description": "Full URL to the booking page for this team event type. Null for managed team event types or when the team does not have a slug.", "example": "https://cal.com/team/acme/30min", "format": "uri" }, "ownerId": { "type": "number", "nullable": true }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/TeamEventTypeResponseHost" } }, "assignAllTeamMembers": { "type": "boolean" }, "schedulingType": { "nullable": true, "type": "string", "enum": ["roundRobin", "collective", "managed"] }, "team": { "$ref": "#/components/schemas/EventTypeTeam" }, "rescheduleWithSameRoundRobinHost": { "type": "boolean", "description": "Rescheduled events will be assigned to the same host as initially scheduled." }, "allowRRHostChoiceOnReschedule": { "type": "boolean", "description": "Let the person rescheduling choose between keeping the original host and letting round robin pick from the whole team." }, "isRRWeightsEnabled": { "type": "boolean", "description": "Only relevant for round robin event types. If true, bookings are distributed according to each host's `weight` instead of evenly." }, "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "The event type's default, custom, and workflow-added booking fields." }, "crm": { "description": "CRM app settings configured for this event type, mirroring the event type Apps tab toggles.", "allOf": [ { "$ref": "#/components/schemas/CrmSettingsOutput_2026_06_12" } ] }, "uuid": { "type": "string", "format": "uuid", "example": "018ff5cd-6dc4-7d57-bcbc-374702ca8b38" }, "parentLinkUid": { "type": "string", "nullable": true, "format": "uuid", "description": "The uuid of the managed parent link this link was created from." } }, "required": [ "lengthInMinutes", "title", "slug", "description", "locations", "disableGuests", "recurrence", "metadata", "price", "currency", "lockTimeZoneToggleOnBookingPage", "forwardParamsSuccessRedirect", "successRedirectUrl", "isInstantEvent", "scheduleId", "hidden", "bookingRequiresAuthentication", "teamId", "bookingUrl", "hosts", "schedulingType", "team", "bookingFields", "crm", "uuid", "parentLinkUid" ] }, "GetLinkOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "oneOf": [ { "title": "Link", "$ref": "#/components/schemas/LinkOutput" }, { "title": "Team Link", "$ref": "#/components/schemas/TeamLinkOutput" } ] } }, "required": ["status", "data"] }, "DeleteLinkData": { "type": "object", "properties": { "lengthInMinutes": { "type": "number", "example": 60 }, "title": { "type": "string", "example": "Learn the secrets of masterchief!" }, "uuid": { "type": "string", "format": "uuid", "example": "018ff5cd-6dc4-7d57-bcbc-374702ca8b38" }, "slug": { "type": "string" } }, "required": ["lengthInMinutes", "title", "uuid", "slug"] }, "DeleteLinkOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/DeleteLinkData" } }, "required": ["status", "data"] }, "BookingInputAddressLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "address", "description": "only allowed value for type is `address` - it refers to address defined by the organizer." } }, "required": ["type"] }, "BookingInputAttendeeAddressLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeeAddress", "description": "only allowed value for type is `attendeeAddress`" }, "address": { "type": "string", "minLength": 1, "example": "123 Example St, City, Country" } }, "required": ["type", "address"] }, "BookingInputAttendeeDefinedLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeeDefined", "description": "only allowed value for type is `attendeeDefined`" }, "location": { "type": "string", "minLength": 1, "example": "321 Example St, City, Country" } }, "required": ["type", "location"] }, "BookingInputAttendeePhoneLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeePhone", "description": "only allowed value for type is `attendeePhone`" }, "phone": { "type": "string", "example": "+37120993151" } }, "required": ["type", "phone"] }, "BookingInputIntegrationLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "integration", "description": "only allowed value for type is `integration`" }, "integration": { "enum": [ "cal-video", "google-meet", "zoom", "whereby-video", "whatsapp-video", "webex-video", "telegram-video", "tandem", "sylaps-video", "skype-video", "sirius-video", "signal-video", "shimmer-video", "salesroom-video", "roam-video", "riverside-video", "ping-video", "office365-video", "mirotalk-video", "jitsi", "jelly-video", "jelly-conferencing", "huddle", "facetime-video", "element-call-video", "eightxeight-video", "discord-video", "demodesk-video", "campfire-video" ], "type": "string", "example": "cal-video" } }, "required": ["type", "integration"] }, "BookingInputLinkLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "link", "description": "only allowed value for type is `link` - it refers to link defined by the organizer." } }, "required": ["type"] }, "BookingInputPhoneLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "phone", "description": "only allowed value for type is `phone` - it refers to phone defined by the organizer." } }, "required": ["type"] }, "BookingInputOrganizersDefaultAppLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "organizersDefaultApp", "description": "only available for team event types and the only allowed value for type is `organizersDefaultApp` - it refers to the default app defined by the organizer." } }, "required": ["type"] }, "CreateBookingAttendee": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the attendee.", "example": "John Doe" }, "timeZone": { "type": "string", "description": "The time zone of the attendee.", "example": "America/New_York" }, "phoneNumber": { "type": "string", "description": "The phone number of the attendee in international format.", "example": "+919876543210" }, "language": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The preferred language of the attendee. Used for booking confirmation.", "example": "it", "default": "en" }, "email": { "type": "string", "description": "The email of the attendee.", "example": "john.doe@example.com" } }, "required": ["name", "timeZone"] }, "CreateBookingInput_2024_08_13": { "type": "object", "properties": { "start": { "type": "string", "description": "The start time of the booking in ISO 8601 format in UTC timezone.", "example": "2024-08-13T09:00:00Z", "format": "date-time" }, "attendee": { "description": "The attendee's details.", "allOf": [ { "$ref": "#/components/schemas/CreateBookingAttendee" } ] }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values for custom booking fields added by you.", "example": { "customField": "customValue" } }, "leadEnrichmentOptOut": { "type": "boolean", "description": "The booker's answer to the lead enrichment opt-out, for an event type with a workflow that looks bookers up with lead enrichment. Send `true` when the booker ticked the opt-out and `false` when they were shown it and left it unticked. Sending `false` asserts that the booker saw the opt-out. Leave it out when the booker was not shown it: a booking without an answer is never looked up.", "example": false }, "eventTypeId": { "type": "number", "description": "The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.", "example": 123 }, "eventTypeSlug": { "type": "string", "description": "The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.", "example": "my-event-type" }, "username": { "type": "string", "description": "The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.", "example": "john-doe" }, "teamSlug": { "type": "string", "description": "Team slug for team that owns event type for which slots are fetched. Required along with eventTypeSlug and optionally organizationSlug if the team is part of organization", "example": "john-doe" }, "organizationSlug": { "type": "string", "description": "The organization slug. Optional, only used when booking with eventTypeSlug + username, eventTypeSlug + teamSlug, or usernames.", "example": "acme-corp" }, "usernames": { "uniqueItems": true, "minItems": 2, "maxItems": 20, "description": "Usernames of the hosts for a dynamic group booking (no stored event type) - every listed user must be available. Must contain 2 to 20 distinct usernames, and can't be combined with eventTypeId, eventTypeSlug, username or teamSlug. Pass organizationSlug when the users belong to an organization; without it only users outside any organization are found. Platform managed users can only be booked with their own OAuth client's credentials or one of its access tokens; to any other request they are reported as not found. Duration defaults to 30 minutes and can be changed with lengthInMinutes (15, 30, 45, 60 or 90).", "example": ["alice", "bob"], "type": "array", "items": { "type": "string" } }, "guests": { "description": "An optional list of guest emails attending the event.", "example": ["guest1@example.com", "guest2@example.com"], "type": "array", "items": { "type": "string" } }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.", "example": "https://example.com/meeting", "deprecated": true }, "location": { "description": "One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.", "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/BookingInputAddressLocation_2024_08_13" }, { "title": "Attendee Address", "$ref": "#/components/schemas/BookingInputAttendeeAddressLocation_2024_08_13" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/BookingInputAttendeeDefinedLocation_2024_08_13" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/BookingInputAttendeePhoneLocation_2024_08_13" }, { "title": "Integration", "$ref": "#/components/schemas/BookingInputIntegrationLocation_2024_08_13" }, { "title": "Link", "$ref": "#/components/schemas/BookingInputLinkLocation_2024_08_13" }, { "title": "Phone", "$ref": "#/components/schemas/BookingInputPhoneLocation_2024_08_13" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/BookingInputOrganizersDefaultAppLocation_2024_08_13" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.", "example": { "key": "value" } }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 30, "description": "If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here.\n If not provided then event type default length will be used for the booking." }, "routing": { "description": "Routing information from routing forms that determined the booking assignment. Both responseId and teamMemberIds are required if provided.", "example": { "responseId": 123, "teamMemberIds": [101, 102] }, "allOf": [ { "$ref": "#/components/schemas/Routing" } ] }, "emailVerificationCode": { "type": "string", "description": "Email verification code required when event type has email verification enabled.", "example": "123456" }, "allowConflicts": { "type": "boolean", "description": "When true, availability conflict checks are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "allowBookingOutOfBounds": { "type": "boolean", "description": "When true, booking time out-of-bounds checks are bypassed, allowing bookings outside the normally permitted scheduling window, for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "skipBookingLimits": { "type": "boolean", "description": "When true, booking limit checks (event type, team, and per-host count and duration limits) are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true } }, "required": ["start", "attendee"] }, "CreateInstantBookingInput_2024_08_13": { "type": "object", "properties": { "attendee": { "description": "The attendee's details.", "allOf": [ { "$ref": "#/components/schemas/CreateBookingAttendee" } ] }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values for custom booking fields added by you.", "example": { "customField": "customValue" } }, "leadEnrichmentOptOut": { "type": "boolean", "description": "The booker's answer to the lead enrichment opt-out, for an event type with a workflow that looks bookers up with lead enrichment. Send `true` when the booker ticked the opt-out and `false` when they were shown it and left it unticked. Sending `false` asserts that the booker saw the opt-out. Leave it out when the booker was not shown it: a booking without an answer is never looked up.", "example": false }, "eventTypeId": { "type": "number", "description": "The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.", "example": 123 }, "eventTypeSlug": { "type": "string", "description": "The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.", "example": "my-event-type" }, "username": { "type": "string", "description": "The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.", "example": "john-doe" }, "teamSlug": { "type": "string", "description": "Team slug for team that owns event type for which slots are fetched. Required along with eventTypeSlug and optionally organizationSlug if the team is part of organization", "example": "john-doe" }, "organizationSlug": { "type": "string", "description": "The organization slug. Optional, only used when booking with eventTypeSlug + username, eventTypeSlug + teamSlug, or usernames.", "example": "acme-corp" }, "guests": { "description": "An optional list of guest emails attending the event.", "example": ["guest1@example.com", "guest2@example.com"], "type": "array", "items": { "type": "string" } }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.", "example": "https://example.com/meeting", "deprecated": true }, "location": { "description": "One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.", "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/BookingInputAddressLocation_2024_08_13" }, { "title": "Attendee Address", "$ref": "#/components/schemas/BookingInputAttendeeAddressLocation_2024_08_13" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/BookingInputAttendeeDefinedLocation_2024_08_13" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/BookingInputAttendeePhoneLocation_2024_08_13" }, { "title": "Integration", "$ref": "#/components/schemas/BookingInputIntegrationLocation_2024_08_13" }, { "title": "Link", "$ref": "#/components/schemas/BookingInputLinkLocation_2024_08_13" }, { "title": "Phone", "$ref": "#/components/schemas/BookingInputPhoneLocation_2024_08_13" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/BookingInputOrganizersDefaultAppLocation_2024_08_13" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.", "example": { "key": "value" } }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 30, "description": "If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here.\n If not provided then event type default length will be used for the booking." }, "routing": { "description": "Routing information from routing forms that determined the booking assignment. Both responseId and teamMemberIds are required if provided.", "example": { "responseId": 123, "teamMemberIds": [101, 102] }, "allOf": [ { "$ref": "#/components/schemas/Routing" } ] }, "emailVerificationCode": { "type": "string", "description": "Email verification code required when event type has email verification enabled.", "example": "123456" }, "allowConflicts": { "type": "boolean", "description": "When true, availability conflict checks are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "allowBookingOutOfBounds": { "type": "boolean", "description": "When true, booking time out-of-bounds checks are bypassed, allowing bookings outside the normally permitted scheduling window, for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "skipBookingLimits": { "type": "boolean", "description": "When true, booking limit checks (event type, team, and per-host count and duration limits) are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "start": { "type": "string", "description": "The start time of the instant meeting in ISO 8601 format in UTC timezone. Defaults to the time the request is received.", "example": "2024-08-13T09:00:00Z", "format": "date-time" }, "instant": { "type": "boolean", "description": "Flag indicating if the booking is an instant booking. Only available for team events.", "example": true }, "instantMeetingExpiresInSeconds": { "type": "number", "minimum": 1, "description": "How many seconds hosts have to accept the instant meeting. It can only shorten the event type's instant meeting expiry setting, which defaults to 90 seconds: a longer value is capped to that setting, and leaving it out uses the setting. The applied value is returned as instantMeetingExpiresInSeconds.", "example": 120 } }, "required": ["attendee", "instant"] }, "CreateRecurringBookingInput_2024_08_13": { "type": "object", "properties": { "start": { "type": "string", "description": "The start time of the booking in ISO 8601 format in UTC timezone.", "example": "2024-08-13T09:00:00Z", "format": "date-time" }, "attendee": { "description": "The attendee's details.", "allOf": [ { "$ref": "#/components/schemas/CreateBookingAttendee" } ] }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values for custom booking fields added by you.", "example": { "customField": "customValue" } }, "leadEnrichmentOptOut": { "type": "boolean", "description": "The booker's answer to the lead enrichment opt-out, for an event type with a workflow that looks bookers up with lead enrichment. Send `true` when the booker ticked the opt-out and `false` when they were shown it and left it unticked. Sending `false` asserts that the booker saw the opt-out. Leave it out when the booker was not shown it: a booking without an answer is never looked up.", "example": false }, "eventTypeId": { "type": "number", "description": "The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.", "example": 123 }, "eventTypeSlug": { "type": "string", "description": "The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.", "example": "my-event-type" }, "username": { "type": "string", "description": "The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.", "example": "john-doe" }, "teamSlug": { "type": "string", "description": "Team slug for team that owns event type for which slots are fetched. Required along with eventTypeSlug and optionally organizationSlug if the team is part of organization", "example": "john-doe" }, "organizationSlug": { "type": "string", "description": "The organization slug. Optional, only used when booking with eventTypeSlug + username, eventTypeSlug + teamSlug, or usernames.", "example": "acme-corp" }, "guests": { "description": "An optional list of guest emails attending the event.", "example": ["guest1@example.com", "guest2@example.com"], "type": "array", "items": { "type": "string" } }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.", "example": "https://example.com/meeting", "deprecated": true }, "location": { "description": "One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.", "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/BookingInputAddressLocation_2024_08_13" }, { "title": "Attendee Address", "$ref": "#/components/schemas/BookingInputAttendeeAddressLocation_2024_08_13" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/BookingInputAttendeeDefinedLocation_2024_08_13" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/BookingInputAttendeePhoneLocation_2024_08_13" }, { "title": "Integration", "$ref": "#/components/schemas/BookingInputIntegrationLocation_2024_08_13" }, { "title": "Link", "$ref": "#/components/schemas/BookingInputLinkLocation_2024_08_13" }, { "title": "Phone", "$ref": "#/components/schemas/BookingInputPhoneLocation_2024_08_13" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/BookingInputOrganizersDefaultAppLocation_2024_08_13" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.", "example": { "key": "value" } }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 30, "description": "If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here.\n If not provided then event type default length will be used for the booking." }, "routing": { "description": "Routing information from routing forms that determined the booking assignment. Both responseId and teamMemberIds are required if provided.", "example": { "responseId": 123, "teamMemberIds": [101, 102] }, "allOf": [ { "$ref": "#/components/schemas/Routing" } ] }, "emailVerificationCode": { "type": "string", "description": "Email verification code required when event type has email verification enabled.", "example": "123456" }, "allowConflicts": { "type": "boolean", "description": "When true, availability conflict checks are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "allowBookingOutOfBounds": { "type": "boolean", "description": "When true, booking time out-of-bounds checks are bypassed, allowing bookings outside the normally permitted scheduling window, for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "skipBookingLimits": { "type": "boolean", "description": "When true, booking limit checks (event type, team, and per-host count and duration limits) are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "recurrenceCount": { "type": "number", "minimum": 1, "description": "The number of recurrences. If not provided then event type recurrence count will be used. Can't be more than\n event type recurrence count", "example": 5, "maximum": 32 } }, "required": ["start", "attendee"] }, "BookingHost": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "example": "jane100@example.com" }, "displayEmail": { "type": "string", "example": "jane100@example.com", "description": "Clean email for display purposes" }, "username": { "type": "string", "example": "jane100" }, "timeZone": { "type": "string", "example": "America/Los_Angeles" } }, "required": ["id", "uuid", "name", "email", "displayEmail", "username", "timeZone"] }, "EventType": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "slug": { "type": "string", "example": "some-event" } }, "required": ["id", "slug"] }, "BookingAttendee": { "type": "object", "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "displayEmail": { "type": "string", "example": "john@example.com", "description": "Clean email for display purposes" }, "timeZone": { "type": "string", "example": "America/New_York" }, "language": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "absent": { "type": "boolean", "example": false }, "phoneNumber": { "type": "string", "example": "+1234567890" } }, "required": ["name", "email", "displayEmail", "timeZone", "absent"] }, "BookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAttendee" } }, "guests": { "example": ["guest1@example.com", "guest2@example.com"], "type": "array", "items": { "type": "string" } }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values.", "example": { "customField": "customValue" } } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "attendees", "bookingFieldsResponses" ] }, "InstantBookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAttendee" } }, "guests": { "example": ["guest1@example.com", "guest2@example.com"], "type": "array", "items": { "type": "string" } }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values.", "example": { "customField": "customValue" } }, "instantMeetingExpiresAt": { "type": "string", "example": "2024-08-13T15:32:00.000Z", "description": "When the instant meeting request expires if no host has accepted it." }, "instantMeetingExpiresInSeconds": { "type": "number", "example": 120, "description": "The seconds hosts have to accept the instant meeting: the requested instantMeetingExpiresInSeconds capped to the event type's instant meeting expiry setting, or that setting when none was requested." } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "attendees", "bookingFieldsResponses", "instantMeetingExpiresAt", "instantMeetingExpiresInSeconds" ] }, "RecurringBookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAttendee" } }, "guests": { "example": ["guest1@example.com", "guest2@example.com"], "type": "array", "items": { "type": "string" } }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values.", "example": { "customField": "customValue" } }, "recurringBookingUid": { "type": "string", "example": "recurring_uid_987" } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "attendees", "bookingFieldsResponses", "recurringBookingUid" ] }, "SeatedAttendee": { "type": "object", "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "displayEmail": { "type": "string", "example": "john@example.com", "description": "Clean email for display purposes" }, "timeZone": { "type": "string", "example": "America/New_York" }, "language": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "absent": { "type": "boolean", "example": false }, "phoneNumber": { "type": "string", "example": "+1234567890" }, "seatUid": { "type": "string", "example": "3be561a9-31f1-4b8e-aefc-9d9a085f0dd1" }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "description": "The date and time when the attendee joined the seated booking." }, "bookingFieldsResponses": { "type": "object", "additionalProperties": true, "description": "Booking field responses consisting of an object with booking field slug as keys and user response as values.", "example": { "customField": "customValue" } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "status": { "type": "string", "enum": ["cancelled"], "example": "cancelled", "description": "Present on API version 2026-02-25 and later when this attendee was loaded from a cancelled seat. Omitted for occupied seats." }, "confirmationStatus": { "type": "string", "enum": ["pending", "accepted", "rejected"], "example": "accepted", "description": "Confirmation verdict of this live seat. Omitted when the attendee has no live seat. An attendee loaded from a cancelled seat has status cancelled and does not include confirmationStatus." } }, "required": [ "name", "email", "displayEmail", "timeZone", "absent", "seatUid", "bookingFieldsResponses" ] }, "CreateSeatedBookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "seatUid": { "type": "string", "example": "3be561a9-31f1-4b8e-aefc-9d9a085f0dd1" }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/SeatedAttendee" } } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "seatUid", "attendees" ] }, "CreateRecurringSeatedBookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "seatUid": { "type": "string", "example": "3be561a9-31f1-4b8e-aefc-9d9a085f0dd1" }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/SeatedAttendee" } }, "recurringBookingUid": { "type": "string", "example": "recurring_uid_987" } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "seatUid", "attendees", "recurringBookingUid" ] }, "CreateBookingOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Instant Booking", "$ref": "#/components/schemas/InstantBookingOutput_2024_08_13" }, { "title": "Recurring Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" } }, { "title": "Seated Booking", "$ref": "#/components/schemas/CreateSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/CreateRecurringSeatedBookingOutput_2024_08_13" } } ], "description": "Booking data, which can be either a BookingOutput object or an array of RecurringBookingOutput objects" } }, "required": ["status", "data"] }, "GetSeatedBookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/SeatedAttendee" } } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "attendees" ] }, "GetRecurringSeatedBookingOutput_2024_08_13": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uid": { "type": "string", "example": "booking_uid_123" }, "title": { "type": "string", "example": "Consultation" }, "description": { "type": "string", "example": "Learn how to integrate scheduling into marketplace." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingHost" } }, "status": { "type": "string", "enum": ["cancelled", "accepted", "rejected", "pending", "awaiting_host"], "example": "accepted", "description": "`awaiting_host` is an instant meeting that is live and waiting for a host to join." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelledByEmail": { "type": "string", "format": "email", "example": "canceller@example.com" }, "reschedulingReason": { "type": "string", "example": "User rescheduled the event" }, "rescheduledByEmail": { "type": "string", "format": "email", "example": "rescheduler@example.com" }, "rescheduledFromUid": { "type": "string", "example": "previous_uid_123", "description": "UID of the previous booking from which this booking was rescheduled." }, "rescheduledToUid": { "type": "string", "example": "new_uid_456", "description": "UID of the new booking to which this booking was rescheduled." }, "start": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "end": { "type": "string", "example": "2024-08-13T16:30:00Z", "format": "date-time" }, "duration": { "type": "number", "example": 60 }, "eventTypeId": { "type": "number", "example": 50, "deprecated": true, "description": "Deprecated - rely on 'eventType' object containing the id instead." }, "eventType": { "$ref": "#/components/schemas/EventType" }, "eventUuid": { "type": "string", "nullable": true, "example": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e", "description": "UUID of the Event this booking belongs to. Pass it to `GET /v2/events/{uuid}` to fetch the Event. `null` when the booking is not for an Event." }, "meetingUrl": { "type": "string", "format": "uri", "description": "Deprecated - rely on 'location' field instead.", "example": "https://example.com/recurring-meeting", "deprecated": true }, "location": { "type": "string", "example": "https://example.com/meeting" }, "absentHost": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "example": "2024-08-13T15:30:00Z", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "key": "value" } }, "rating": { "type": "number", "example": 4 }, "icsUid": { "type": "string", "example": "ics_uid_123", "description": "UID of ICS event." }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/SeatedAttendee" } }, "recurringBookingUid": { "type": "string", "example": "recurring_uid_987" } }, "required": [ "id", "uid", "title", "description", "hosts", "status", "start", "end", "duration", "eventTypeId", "eventType", "location", "absentHost", "createdAt", "updatedAt", "attendees", "recurringBookingUid" ] }, "GetBookingOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Recurring Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" } }, { "title": "Seated Booking", "$ref": "#/components/schemas/GetSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" } } ], "description": "Booking data, which can be either a BookingOutput object, a RecurringBookingOutput object, or an array of RecurringBookingOutput objects" } }, "required": ["status", "data"] }, "RecordingItem": { "type": "object", "properties": { "id": { "type": "string", "example": "1234567890" }, "roomName": { "type": "string", "example": "daily-video-room-123" }, "startTs": { "type": "number", "example": 1678901234 }, "status": { "type": "string", "example": "completed" }, "maxParticipants": { "type": "number", "example": 10 }, "duration": { "type": "number", "example": 3600 }, "shareToken": { "type": "string", "example": "share-token-123" }, "downloadLink": { "type": "string", "nullable": true, "format": "uri", "description": "Temporary recording download URL. Valid for 1 hour; request fresh recordings after expiration.", "example": "https://cal-video-recordings.s3.us-east-2.amazonaws.com/meetco/123s" }, "error": { "type": "string", "nullable": true, "example": "Error message" } }, "required": ["id", "roomName", "startTs", "status", "duration", "shareToken"] }, "GetBookingRecordingsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordingItem" } } }, "required": ["status", "data"] }, "GetBookingTranscriptsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "example": ["https://transcript1.com", "https://transcript2.com"], "type": "array", "items": { "type": "string" } } }, "required": ["status", "data"] }, "GetBookingsOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Seated Booking", "$ref": "#/components/schemas/GetSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" } ] }, "description": "Array of booking data, which can contain either BookingOutput objects or RecurringBookingOutput objects" }, "pagination": { "$ref": "#/components/schemas/PaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "RescheduleBookingInput_2024_08_13": { "type": "object", "properties": { "start": { "type": "string", "description": "Start time in ISO 8601 format for the new booking", "example": "2024-08-13T10:00:00Z", "format": "date-time" }, "lengthInMinutes": { "type": "number", "minimum": 1, "example": 30, "description": "If the event type has multiple possible lengths, you can pass the new booking length here. If not provided then the original booking length is kept." }, "rescheduledBy": { "type": "string", "description": "Email of the person who is rescheduling the booking - only needed when rescheduling a booking that requires a confirmation.\nIf event type owner email is provided then rescheduled booking will be automatically confirmed. If attendee email or no email is passed then the event type\nowner will have to confirm the rescheduled booking." }, "reschedulingReason": { "type": "string", "example": "User requested reschedule", "description": "Reason for rescheduling the booking" }, "emailVerificationCode": { "type": "string", "description": "Email verification code required when event type has email verification enabled.", "example": "123456" }, "rescheduleWithSameHost": { "type": "boolean", "description": "Only for round robin event types that let the person rescheduling choose the host. True keeps the original host, false lets round robin pick from the whole team. Ignored for every other event type.", "example": true }, "allowConflicts": { "type": "boolean", "description": "When true, availability conflict checks are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "allowBookingOutOfBounds": { "type": "boolean", "description": "When true, booking time out-of-bounds checks are bypassed, allowing bookings outside the normally permitted scheduling window, for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "skipBookingLimits": { "type": "boolean", "description": "When true, booking limit checks (event type, team, and per-host count and duration limits) are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true } }, "required": ["start"] }, "RescheduleSeatedBookingInput_2024_08_13": { "type": "object", "properties": { "start": { "type": "string", "description": "Start time in ISO 8601 format for the new booking", "example": "2024-08-13T10:00:00Z", "format": "date-time" }, "rescheduledBy": { "type": "string", "description": "Email of the person who is rescheduling the booking - only needed when rescheduling a booking that requires a confirmation.\nIf event type owner email is provided then rescheduled booking will be automatically confirmed. If attendee email or no email is passed then the event type\nowner will have to confirm the rescheduled booking." }, "seatUid": { "type": "string", "example": "3be561a9-31f1-4b8e-aefc-9d9a085f0dd1", "description": "Uid of the specific seat within booking." }, "emailVerificationCode": { "type": "string", "description": "Email verification code required when event type has email verification enabled.", "example": "123456" }, "allowConflicts": { "type": "boolean", "description": "When true, availability conflict checks are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "allowBookingOutOfBounds": { "type": "boolean", "description": "When true, booking time out-of-bounds checks are bypassed, allowing bookings outside the normally permitted scheduling window, for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true }, "skipBookingLimits": { "type": "boolean", "description": "When true, booking limit checks (event type, team, and per-host count and duration limits) are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.", "example": true } }, "required": ["start", "seatUid"] }, "RescheduleBookingOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Seated Booking", "$ref": "#/components/schemas/CreateSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/CreateRecurringSeatedBookingOutput_2024_08_13" } ], "description": "Booking data, which can be either a BookingOutput object or a RecurringBookingOutput object" } }, "required": ["status", "data"] }, "CancelBookingInput_2024_08_13": { "type": "object", "properties": { "cancellationReason": { "type": "string", "example": "User requested cancellation" }, "cancelSubsequentBookings": { "type": "boolean", "description": "For recurring non-seated booking only - if true, cancel booking with the bookingUid of the individual recurrence and all recurrences that come after it." } } }, "CancelSeatedBookingInput_2024_08_13": { "type": "object", "properties": { "seatUid": { "type": "string", "example": "3be561a9-31f1-4b8e-aefc-9d9a085f0dd1", "description": "Uid of the specific seat within booking." }, "cancellationReason": { "type": "string", "example": "User requested cancellation" } }, "required": ["seatUid"] }, "CancelBookingOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Recurring Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" } }, { "title": "Seated Booking", "$ref": "#/components/schemas/GetSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" } } ], "description": "Booking data, which can be either a BookingOutput object, a RecurringBookingOutput object, or an array of RecurringBookingOutput objects" } }, "required": ["status", "data"] }, "MarkAbsentAttendee": { "type": "object", "properties": { "email": { "type": "string" }, "absent": { "type": "boolean" } }, "required": ["email", "absent"] }, "MarkAbsentBookingInput_2024_08_13": { "type": "object", "properties": { "host": { "type": "boolean", "example": false, "description": "Whether the host was absent" }, "attendees": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/MarkAbsentAttendee" } } } }, "MarkAbsentBookingOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" } ], "description": "Booking data, which can be either a BookingOutput object or a RecurringBookingOutput object" } }, "required": ["status", "data"] }, "ReassignedToDto": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "displayEmail": { "type": "string", "example": "john.doe@example.com", "description": "Clean email for display purposes" } }, "required": ["id", "name", "email", "displayEmail"] }, "ReassignBookingOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Reassigned Booking", "$ref": "#/components/schemas/ReassignBookingOutput_2024_08_13" } ], "description": "Booking data, which can be either a ReassignAutoBookingOutput object or a ReassignManualBookingOutput object", "allOf": [ { "$ref": "#/components/schemas/ReassignBookingOutput_2024_08_13" } ] } }, "required": ["status", "data"] }, "ReassignToUserBookingInput_2024_08_13": { "type": "object", "properties": { "reason": { "type": "string", "example": "Host has to take another call", "description": "Reason for reassigning the booking" } } }, "ConfirmBookingSeatsInput_2024_08_13": { "type": "object", "properties": { "seatUids": { "minItems": 1, "maxItems": 500, "description": "Seat UIDs to confirm. A seat that is already confirmed stays confirmed. Duplicate UIDs in one request are confirmed once.", "example": ["3be561a9-31f1-4b8e-aefc-9d9a085f0dd1"], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": ["seatUids"] }, "ConfirmBookingSeatsData_2024_08_13": { "type": "object", "properties": { "confirmedSeatUids": { "description": "Seat UIDs that were waiting for confirmation and are now confirmed. Seats that were already confirmed are omitted.", "example": ["3be561a9-31f1-4b8e-aefc-9d9a085f0dd1"], "type": "array", "items": { "type": "string" } } }, "required": ["confirmedSeatUids"] }, "ConfirmBookingSeatsOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ConfirmBookingSeatsData_2024_08_13" } }, "required": ["status", "data"] }, "DeclineBookingSeatsInput_2024_08_13": { "type": "object", "properties": { "seatUids": { "minItems": 1, "maxItems": 500, "description": "Seat UIDs to decline. A waiting or confirmed seat becomes declined. A seat that is already declined stays declined. Duplicate UIDs in one request are declined once.", "example": ["3be561a9-31f1-4b8e-aefc-9d9a085f0dd1"], "type": "array", "items": { "type": "string", "minLength": 1 } }, "reason": { "type": "string", "maxLength": 1000, "example": "No availability that week", "description": "Reason for declining these seats. Shown on each declined seat's email and in that seat's booking-rejected workflow. Omit it to decline without a reason." } }, "required": ["seatUids"] }, "DeclineBookingSeatsData_2024_08_13": { "type": "object", "properties": { "declinedSeatUids": { "description": "Seat UIDs that were waiting or confirmed and are now declined. Seats that were already declined are omitted.", "example": ["3be561a9-31f1-4b8e-aefc-9d9a085f0dd1"], "type": "array", "items": { "type": "string" } } }, "required": ["declinedSeatUids"] }, "DeclineBookingSeatsOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DeclineBookingSeatsData_2024_08_13" } }, "required": ["status", "data"] }, "DeclineBookingInput_2024_08_13": { "type": "object", "properties": { "reason": { "type": "string", "example": "Host has to take another call", "description": "Reason for declining a booking that requires a confirmation" } } }, "RequestRescheduleInput_2024_08_13": { "type": "object", "properties": { "rescheduleReason": { "type": "string", "example": "I need to reschedule due to a conflict", "description": "Reason for requesting to reschedule the booking" } } }, "RequestRescheduleOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "CalendarLink": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the calendar link" }, "link": { "type": "string", "description": "The link to the calendar" } }, "required": ["label", "link"] }, "CalendarLinksOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "description": "The status of the request, always 'success' for successful responses", "example": "success" }, "data": { "description": "Calendar links for the booking", "type": "array", "items": { "$ref": "#/components/schemas/CalendarLink" } } }, "required": ["status", "data"] }, "BookingReference": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the booking reference" }, "eventUid": { "type": "string", "description": "The event uid of the booking" }, "destinationCalendarId": { "type": "string", "nullable": true, "description": "The id of the calendar the event is created in" }, "id": { "type": "number", "description": "The id of the booking reference" } }, "required": ["type", "eventUid", "destinationCalendarId", "id"] }, "BookingReferencesOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "description": "The status of the request, always 'success' for successful responses", "example": "success" }, "data": { "description": "Booking References", "type": "array", "items": { "$ref": "#/components/schemas/BookingReference" } } }, "required": ["status", "data"] }, "CalMeetingParticipant": { "type": "object", "properties": { "userId": { "type": "string", "nullable": true, "example": "user123" }, "userName": { "type": "string", "nullable": true, "example": "John Doe" }, "joinTime": { "type": "number", "example": 1678901234 }, "duration": { "type": "number", "example": 3600 } }, "required": ["userId", "userName", "joinTime", "duration"] }, "CalMeetingSession": { "type": "object", "properties": { "id": { "type": "string", "example": "session123" }, "room": { "type": "string", "example": "daily-video-room-123" }, "startTime": { "type": "number", "example": 1678901234 }, "duration": { "type": "number", "example": 3600 }, "ongoing": { "type": "boolean", "example": false }, "maxParticipants": { "type": "number", "example": 10 }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/CalMeetingParticipant" } } }, "required": ["id", "room", "startTime", "duration", "ongoing", "maxParticipants", "participants"] }, "GetBookingVideoSessionsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalMeetingSession" } } }, "required": ["status", "data"] }, "BookingAttendeeWithId_2024_08_13": { "type": "object", "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "displayEmail": { "type": "string", "example": "john@example.com", "description": "Clean email for display purposes" }, "timeZone": { "type": "string", "example": "America/New_York" }, "language": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "absent": { "type": "boolean", "example": false }, "phoneNumber": { "type": "string", "example": "+1234567890" }, "id": { "type": "number", "example": 251 } }, "required": ["name", "email", "displayEmail", "timeZone", "absent", "id"] }, "GetBookingAttendeesOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAttendeeWithId_2024_08_13" } } }, "required": ["status", "data"] }, "GetBookingAttendeeOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/BookingAttendeeWithId_2024_08_13" } }, "required": ["status", "data"] }, "AddAttendeeInput_2024_08_13": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the attendee.", "example": "John Doe" }, "timeZone": { "type": "string", "description": "The time zone of the attendee.", "example": "America/New_York" }, "phoneNumber": { "type": "string", "description": "The phone number of the attendee in international format.", "example": "+919876543210" }, "language": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "description": "The preferred language of the attendee. Used for booking confirmation.", "example": "it", "default": "en" }, "email": { "type": "string", "format": "email", "description": "The email of the attendee.", "example": "john.doe@example.com" } }, "required": ["name", "timeZone", "email"] }, "BookingAttendeeOutput_2024_08_13": { "type": "object", "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "displayEmail": { "type": "string", "example": "john@example.com", "description": "Clean email for display purposes" }, "timeZone": { "type": "string", "example": "America/New_York" }, "language": { "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "type": "string", "example": "en" }, "absent": { "type": "boolean", "example": false }, "phoneNumber": { "type": "string", "example": "+1234567890" }, "id": { "type": "number", "example": 251 }, "bookingId": { "type": "number", "example": 313 } }, "required": ["name", "email", "displayEmail", "timeZone", "absent", "id", "bookingId"] }, "AddAttendeeOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/BookingAttendeeOutput_2024_08_13" } }, "required": ["status", "data"] }, "Guest": { "type": "object", "properties": { "email": { "type": "string", "description": "The email of the guest.", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "The name of the guest.", "example": "John Doe" }, "timeZone": { "type": "string", "description": "The time zone of the guest.", "example": "America/New_York" }, "phoneNumber": { "type": "string", "description": "The phone number of the guest in international format.", "example": "+919876543210" }, "language": { "type": "string", "enum": [ "ar", "ca", "de", "es", "eu", "he", "id", "ja", "lv", "pl", "ro", "sr", "th", "vi", "az", "cs", "el", "es-419", "fi", "hr", "it", "km", "nl", "pt", "ru", "sv", "tr", "zh-CN", "bg", "da", "en", "et", "fr", "hu", "iw", "ko", "no", "pt-BR", "sk", "sl", "ta", "uk", "zh-TW", "bn" ], "description": "The preferred language of the guest. Used for booking confirmation.", "example": "it", "default": "en" } }, "required": ["email"] }, "AddGuestsInput_2024_08_13": { "type": "object", "properties": { "guests": { "description": "Array of guests to add to the booking. Maximum 100 guests per request. Required unless `contactIds` or `contactTagIds` is given.", "example": [ { "email": "john.doe@example.com", "name": "John Doe", "timeZone": "America/New_York" }, { "email": "jane.smith@example.com", "name": "Jane Smith" } ], "type": "array", "items": { "$ref": "#/components/schemas/Guest" } }, "contactIds": { "minItems": 1, "description": "Ids of the authenticated user's own contacts, from `GET /v2/contacts`. Each contact is added at its email and with its name, and they count with `guests` and `contactTagIds` toward the 100 guests a booking can have, once per email. Requires the `contacts` feature. A contact the user doesn't own is a 400.", "example": ["0192f3a1-7c2b-7d4e-9a10-0000000000a1"], "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid" } }, "contactTagIds": { "minItems": 1, "description": "Ids of the authenticated user's own contact tags, from the `tags` of each contact in `GET /v2/contacts`. Every contact with one of these tags is added, and they count with `guests` and `contactIds` toward the 100 guests a booking can have, once per email. Tags that don't fit are refused whole. Requires the `contacts` feature. A tag the user doesn't own is a 400.", "example": ["0192f3a1-7c2b-7d4e-9a10-00000000000a"], "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "AddGuestsOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Recurring Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" } }, { "title": "Seated Booking", "$ref": "#/components/schemas/GetSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" } } ], "description": "Booking data, which can be either a BookingOutput object, a RecurringBookingOutput object, or an array of RecurringBookingOutput objects" } }, "required": ["status", "data"] }, "UpdateInputAddressLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "address", "description": "only allowed value for type is `address` - it refers to address defined by the organizer." }, "address": { "type": "string", "minLength": 1, "example": "123 Example St, City, Country" } }, "required": ["type", "address"] }, "UpdateBookingInputAttendeeAddressLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeeAddress", "description": "only allowed value for type is `attendeeAddress`" }, "address": { "type": "string", "minLength": 1, "example": "123 Example St, City, Country" } }, "required": ["type", "address"] }, "UpdateBookingInputAttendeeDefinedLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeeDefined", "description": "only allowed value for type is `attendeeDefined`" }, "location": { "type": "string", "minLength": 1, "example": "321 Example St, City, Country" } }, "required": ["type", "location"] }, "UpdateBookingInputAttendeePhoneLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "attendeePhone", "description": "only allowed value for type is `attendeePhone`" }, "phone": { "type": "string", "example": "+37120993151" } }, "required": ["type", "phone"] }, "UpdateBookingInputIntegrationLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "integration", "description": "only allowed value for type is `integration`" }, "integration": { "enum": [ "cal-video", "google-meet", "zoom", "whereby-video", "whatsapp-video", "webex-video", "telegram-video", "tandem", "sylaps-video", "skype-video", "sirius-video", "signal-video", "shimmer-video", "salesroom-video", "roam-video", "riverside-video", "ping-video", "office365-video", "mirotalk-video", "jitsi", "jelly-video", "jelly-conferencing", "huddle", "facetime-video", "element-call-video", "eightxeight-video", "discord-video", "demodesk-video", "campfire-video" ], "type": "string", "example": "cal-video" } }, "required": ["type", "integration"] }, "UpdateBookingInputLinkLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "link", "description": "only allowed value for type is `link` - it refers to link defined by the organizer." }, "link": { "type": "string", "format": "uri", "example": "https://meet.google.com/txi-fein-xyz" } }, "required": ["type", "link"] }, "UpdateBookingInputPhoneLocation_2024_08_13": { "type": "object", "properties": { "type": { "type": "string", "example": "phone", "description": "only allowed value for type is `phone` - it refers to phone defined by the organizer." }, "phone": { "type": "string", "example": "+37120993151" } }, "required": ["type", "phone"] }, "UpdateBookingLocationInput_2024_08_13": { "type": "object", "properties": { "location": { "description": "One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.", "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/UpdateInputAddressLocation_2024_08_13" }, { "title": "Attendee Address", "$ref": "#/components/schemas/UpdateBookingInputAttendeeAddressLocation_2024_08_13" }, { "title": "Attendee Defined", "$ref": "#/components/schemas/UpdateBookingInputAttendeeDefinedLocation_2024_08_13" }, { "title": "Attendee Phone", "$ref": "#/components/schemas/UpdateBookingInputAttendeePhoneLocation_2024_08_13" }, { "title": "Integration", "$ref": "#/components/schemas/UpdateBookingInputIntegrationLocation_2024_08_13" }, { "title": "Link", "$ref": "#/components/schemas/UpdateBookingInputLinkLocation_2024_08_13" }, { "title": "Phone", "$ref": "#/components/schemas/UpdateBookingInputPhoneLocation_2024_08_13" } ] }, "notifyHosts": { "type": "boolean", "default": true, "description": "Set to false to skip the location-change emails to hosts. Attendee notifications and the BOOKING_LOCATION_UPDATED webhook are unaffected." } } }, "UpdateBookingLocationOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Recurring Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" } }, { "title": "Seated Booking", "$ref": "#/components/schemas/GetSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Bookings (array)", "type": "array", "items": { "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" } } ], "description": "Booking data, which can be either a BookingOutput object, a RecurringBookingOutput object, or an array of RecurringBookingOutput objects" } }, "required": ["status", "data"] }, "RoutingTraceStepOutput_2024_08_13": { "type": "object", "properties": { "message": { "type": "string", "example": "Account found by website match: acme.com" }, "round": { "type": "string", "example": "Exact Match" }, "domain": { "type": "string", "example": "salesforce" }, "step": { "type": "string", "example": "account_found_by_website" }, "timestamp": { "type": "number", "example": 1717000000000 }, "data": { "type": "object", "additionalProperties": true, "description": "Step-specific data payload" } }, "required": ["message", "round", "domain", "step", "timestamp", "data"] }, "RoutingTraceGroupOutput_2024_08_13": { "type": "object", "properties": { "round": { "type": "string", "example": "Exact Match" }, "domain": { "type": "string", "example": "salesforce" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingTraceStepOutput_2024_08_13" } } }, "required": ["round", "domain", "steps"] }, "RoutingTraceFormOutput_2024_08_13": { "type": "object", "properties": { "name": { "type": "string", "example": "Sales Routing Form" }, "description": { "type": "string", "nullable": true, "example": "Routes leads to the right sales rep" } }, "required": ["name"] }, "RoutingTraceFormResponseOutput_2024_08_13": { "type": "object", "properties": { "fieldId": { "type": "string", "example": "Company Size" }, "label": { "type": "string", "example": "Company Size" }, "displayValue": { "type": "string", "example": "Enterprise (1000+)" } }, "required": ["fieldId", "label", "displayValue"] }, "RoutingTraceFormSubmissionOutput_2024_08_13": { "type": "object", "properties": { "form": { "$ref": "#/components/schemas/RoutingTraceFormOutput_2024_08_13" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingTraceFormResponseOutput_2024_08_13" } } }, "required": ["form", "responses"] }, "RoutingTraceDataOutput_2024_08_13": { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingTraceStepOutput_2024_08_13" } }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingTraceGroupOutput_2024_08_13" } }, "formSubmission": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/RoutingTraceFormSubmissionOutput_2024_08_13" } ] } }, "required": ["steps", "groups"] }, "GetBookingRoutingTraceOutput_2024_08_13": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/RoutingTraceDataOutput_2024_08_13" } }, "required": ["status", "data"] }, "ReassignBookingInput_2026_02_25": { "type": "object", "properties": { "userUuid": { "type": "string", "format": "uuid", "description": "UUID of the user to reassign the booking to. Omit it to let Cal.com pick an available round robin host. For a managed event booking, list the eligible users with `GET /v2/bookings/{bookingUid}/reassignment-candidates` and pass a candidate's `uuid`.", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "reason": { "type": "string", "description": "Reason for reassigning the booking. Only recorded when `userUuid` is set.", "example": "Host has to take another call" } } }, "ReassignedToOutput_2026_02_25": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "uuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "displayEmail": { "type": "string", "example": "john.doe@example.com", "description": "Clean email for display purposes" } }, "required": ["id", "uuid", "name", "email", "displayEmail"] }, "ReassignedBookingOutput_2026_02_25": { "type": "object", "properties": { "bookingUid": { "type": "string", "example": "booking_uid_123", "description": "The reassigned booking's uid. For a managed event booking this is a new uid, because the booking is recreated on the new host's event type." }, "reassignedTo": { "$ref": "#/components/schemas/ReassignedToOutput_2026_02_25" } }, "required": ["bookingUid", "reassignedTo"] }, "ReassignBookingOutput_2026_02_25": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ReassignedBookingOutput_2026_02_25" } }, "required": ["status", "data"] }, "CursorPaginationMeta_2026_05_01": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor to fetch the next page. Pass this value as the `cursor` query parameter on the next request. `null` when `hasMore` is `false`.", "example": "eyJ2IjoxLCJzb3J0VXVpZCI6IjAxOGY0YzJlLTNmMWEtN2FiYy05ZGVmLTAxMjM0NTY3ODlhYiJ9" }, "hasMore": { "type": "boolean", "description": "Whether more pages are available after this one.", "example": true } }, "required": ["nextCursor", "hasMore"] }, "GetBookingsOutput_2026_05_01": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Booking", "$ref": "#/components/schemas/BookingOutput_2024_08_13" }, { "title": "Recurring Booking", "$ref": "#/components/schemas/RecurringBookingOutput_2024_08_13" }, { "title": "Seated Booking", "$ref": "#/components/schemas/GetSeatedBookingOutput_2024_08_13" }, { "title": "Recurring Seated Booking", "$ref": "#/components/schemas/GetRecurringSeatedBookingOutput_2024_08_13" } ] }, "description": "Array of booking data, which can contain either BookingOutput objects or RecurringBookingOutput objects" }, "pagination": { "$ref": "#/components/schemas/CursorPaginationMeta_2026_05_01" } }, "required": ["status", "data", "pagination"] }, "CreateTeamMembershipInput": { "type": "object", "properties": { "userId": { "type": "number" }, "accepted": { "type": "boolean", "default": false, "description": "Only applied when the team is an organization sub-team and the user is already an accepted member of the organization, or when the user is a managed user of the team's OAuth client. Otherwise a sub-team membership is created as a pending invite (`accepted: false`) that the user has to accept. A team outside an organization can add only managed users of its OAuth client; any other user returns 403 and has to be invited with an invite link or by email." }, "role": { "default": "MEMBER", "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean", "default": false } }, "required": ["userId"] }, "CreateTeamMembershipOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamMembershipOutput" } }, "required": ["status", "data"] }, "GetTeamMembershipOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamMembershipOutput" } }, "required": ["status", "data"] }, "GetTeamMembershipsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamMembershipOutput" } }, "required": ["status", "data"] }, "UpdateTeamMembershipInput": { "type": "object", "properties": { "accepted": { "type": "boolean", "description": "Setting `true` on a pending membership is only allowed when the team is an organization sub-team and the user is already an accepted member of the organization, or when the user is a managed user of the team's OAuth client; otherwise the request returns 403." }, "role": { "enum": ["MEMBER", "OWNER", "ADMIN"], "type": "string" }, "disableImpersonation": { "type": "boolean" } } }, "UpdateTeamMembershipOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamMembershipOutput" } }, "required": ["status", "data"] }, "DeleteTeamMembershipOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamMembershipOutput" } }, "required": ["status", "data"] }, "TimezoneOutput": { "type": "object", "properties": { "city": { "type": "string", "description": "Name to show the user: a city, or the name of a timezone when the search matched a timezone rather than a city.", "example": "San Francisco" }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone identifier — the value to store and to send back to Cal.com. `null` for the handful of cities the upstream dataset has no timezone for; those cannot be selected, and a `search` never returns one.", "example": "America/Los_Angeles" }, "country": { "type": "string", "description": "Country of a city search result. Absent for timezone names and the unfiltered list.", "example": "United States of America" }, "region": { "type": "string", "description": "State or province of a city search result, when known. Absent for timezone names and the unfiltered list.", "example": "California" }, "pop": { "type": "number", "description": "Population of the city. Absent when the entry is a timezone rather than a city.", "example": 2091036 } }, "required": ["city", "timezone"] }, "GetTimezonesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimezoneOutput" } } }, "required": ["status", "data"] }, "UserWebhookOutputDto": { "type": "object", "properties": { "payloadTemplate": { "type": "string", "description": "The template of the payload that will be sent to the subscriberUrl, check cal.com/help/webhooks for more information", "example": "{\"content\":\"A new event has been scheduled\",\"type\":\"{{type}}\",\"name\":\"{{title}}\",\"organizer\":\"{{organizer.name}}\",\"booker\":\"{{attendees.0.name}}\"}" }, "triggers": { "type": "array", "items": { "type": "string", "enum": [ "BOOKING_CREATED", "BOOKING_PAYMENT_INITIATED", "BOOKING_PAID", "BOOKING_RESCHEDULED", "BOOKING_REQUESTED", "BOOKING_CANCELLED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_NO_SHOW_UPDATED", "BOOKING_LOCATION_UPDATED", "BOOKING_TITLE_UPDATED", "BOOKING_REASSIGNED", "BOOKING_SEAT_ACCEPTED", "FORM_SUBMITTED", "MEETING_ENDED", "MEETING_STARTED", "RECORDING_READY", "INSTANT_MEETING", "INSTANT_MEETING_ACCEPTED", "RECORDING_TRANSCRIPTION_GENERATED", "OOO_CREATED", "AFTER_HOSTS_CAL_VIDEO_NO_SHOW", "AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "FORM_SUBMITTED_NO_EVENT", "ROUTING_FORM_FALLBACK_HIT", "DELEGATION_CREDENTIAL_ERROR", "WRONG_ASSIGNMENT_REPORT", "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED", "DELEGATION_CREDENTIAL_ROTATION_REQUIRED", "DELEGATION_CREDENTIAL_SECRET_ROTATED", "CALENDAR_ENTRY_REJECTED", "CAL_EVENT_REGISTRATION_REQUESTED", "CAL_EVENT_REGISTRATION_CONFIRMED", "CAL_EVENT_REGISTRATION_WAITLISTED", "CAL_EVENT_REGISTRATION_DECLINED", "CAL_EVENT_REGISTRATION_CANCELLED" ] } }, "customHeaders": { "description": "Static headers sent on every delivery. Values are always redacted as `\"***\"`.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookCustomHeaderOutputDto" } }, "time": { "type": "number", "description": "How long after the booking start time the no-show triggers are evaluated", "example": 5 }, "timeUnit": { "enum": ["DAY", "HOUR", "MINUTE"], "type": "string", "description": "The unit of the no-show time value", "example": "MINUTE" }, "version": { "enum": ["2021-10-20", "2026-07-27"], "type": "string", "description": "The payload format version of the webhook. Version 2026-07-27 adds generated ICS calendar content (`attendeeIcsContent`, `organizerIcsContent`) to BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_SEAT_ACCEPTED, and BOOKING_PAID (when the payment accepted the booking) payloads. Every version's builder-produced payload carries a `payload.platformOAuthClientId` field naming the owning platform OAuth client (`null` for non-platform events; for the flat-delivered MEETING_STARTED/MEETING_ENDED bodies the field appears at the top level of the body). Zapier deliveries, custom payload templates that do not reference the field, the `AFTER_HOSTS_CAL_VIDEO_NO_SHOW` / `AFTER_GUESTS_CAL_VIDEO_NO_SHOW` bodies (delivered verbatim from the fire-time blob, never built) and the legacy `FORM_SUBMITTED_NO_EVENT` fallback delivery omit it.", "example": "2021-10-20" }, "userId": { "type": "number" }, "id": { "type": "number" }, "subscriberUrl": { "type": "string" }, "active": { "type": "boolean" }, "secret": { "type": "string" } }, "required": ["payloadTemplate", "triggers", "version", "userId", "id", "subscriberUrl", "active"] }, "UserWebhookOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UserWebhookOutputDto" } }, "required": ["status", "data"] }, "UserWebhooksOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserWebhookOutputDto" } } }, "required": ["status", "data"] }, "EventTypeWebhookOutputDto": { "type": "object", "properties": { "payloadTemplate": { "type": "string", "description": "The template of the payload that will be sent to the subscriberUrl, check cal.com/help/webhooks for more information", "example": "{\"content\":\"A new event has been scheduled\",\"type\":\"{{type}}\",\"name\":\"{{title}}\",\"organizer\":\"{{organizer.name}}\",\"booker\":\"{{attendees.0.name}}\"}" }, "triggers": { "type": "array", "items": { "type": "string", "enum": [ "BOOKING_CREATED", "BOOKING_PAYMENT_INITIATED", "BOOKING_PAID", "BOOKING_RESCHEDULED", "BOOKING_REQUESTED", "BOOKING_CANCELLED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_NO_SHOW_UPDATED", "BOOKING_LOCATION_UPDATED", "BOOKING_TITLE_UPDATED", "BOOKING_REASSIGNED", "BOOKING_SEAT_ACCEPTED", "FORM_SUBMITTED", "MEETING_ENDED", "MEETING_STARTED", "RECORDING_READY", "INSTANT_MEETING", "INSTANT_MEETING_ACCEPTED", "RECORDING_TRANSCRIPTION_GENERATED", "OOO_CREATED", "AFTER_HOSTS_CAL_VIDEO_NO_SHOW", "AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "FORM_SUBMITTED_NO_EVENT", "ROUTING_FORM_FALLBACK_HIT", "DELEGATION_CREDENTIAL_ERROR", "WRONG_ASSIGNMENT_REPORT", "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED", "DELEGATION_CREDENTIAL_ROTATION_REQUIRED", "DELEGATION_CREDENTIAL_SECRET_ROTATED", "CALENDAR_ENTRY_REJECTED", "CAL_EVENT_REGISTRATION_REQUESTED", "CAL_EVENT_REGISTRATION_CONFIRMED", "CAL_EVENT_REGISTRATION_WAITLISTED", "CAL_EVENT_REGISTRATION_DECLINED", "CAL_EVENT_REGISTRATION_CANCELLED" ] } }, "customHeaders": { "description": "Static headers sent on every delivery. Values are always redacted as `\"***\"`.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookCustomHeaderOutputDto" } }, "time": { "type": "number", "description": "How long after the booking start time the no-show triggers are evaluated", "example": 5 }, "timeUnit": { "enum": ["DAY", "HOUR", "MINUTE"], "type": "string", "description": "The unit of the no-show time value", "example": "MINUTE" }, "version": { "enum": ["2021-10-20", "2026-07-27"], "type": "string", "description": "The payload format version of the webhook. Version 2026-07-27 adds generated ICS calendar content (`attendeeIcsContent`, `organizerIcsContent`) to BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_SEAT_ACCEPTED, and BOOKING_PAID (when the payment accepted the booking) payloads. Every version's builder-produced payload carries a `payload.platformOAuthClientId` field naming the owning platform OAuth client (`null` for non-platform events; for the flat-delivered MEETING_STARTED/MEETING_ENDED bodies the field appears at the top level of the body). Zapier deliveries, custom payload templates that do not reference the field, the `AFTER_HOSTS_CAL_VIDEO_NO_SHOW` / `AFTER_GUESTS_CAL_VIDEO_NO_SHOW` bodies (delivered verbatim from the fire-time blob, never built) and the legacy `FORM_SUBMITTED_NO_EVENT` fallback delivery omit it.", "example": "2021-10-20" }, "eventTypeId": { "type": "number" }, "id": { "type": "number" }, "subscriberUrl": { "type": "string" }, "active": { "type": "boolean" }, "secret": { "type": "string" } }, "required": ["payloadTemplate", "triggers", "version", "eventTypeId", "id", "subscriberUrl", "active"] }, "EventTypeWebhookOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventTypeWebhookOutputDto" } }, "required": ["status", "data"] }, "EventTypeWebhooksOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeWebhookOutputDto" } } }, "required": ["status", "data"] }, "DeleteManyWebhooksOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "string" } }, "required": ["status", "data"] }, "OAuthClientWebhookOutputDto": { "type": "object", "properties": { "payloadTemplate": { "type": "string", "description": "The template of the payload that will be sent to the subscriberUrl, check cal.com/help/webhooks for more information", "example": "{\"content\":\"A new event has been scheduled\",\"type\":\"{{type}}\",\"name\":\"{{title}}\",\"organizer\":\"{{organizer.name}}\",\"booker\":\"{{attendees.0.name}}\"}" }, "triggers": { "type": "array", "items": { "type": "string", "enum": [ "BOOKING_CREATED", "BOOKING_PAYMENT_INITIATED", "BOOKING_PAID", "BOOKING_RESCHEDULED", "BOOKING_REQUESTED", "BOOKING_CANCELLED", "BOOKING_REJECTED", "BOOKING_SEAT_REJECTED", "BOOKING_NO_SHOW_UPDATED", "BOOKING_LOCATION_UPDATED", "BOOKING_TITLE_UPDATED", "BOOKING_REASSIGNED", "BOOKING_SEAT_ACCEPTED", "FORM_SUBMITTED", "MEETING_ENDED", "MEETING_STARTED", "RECORDING_READY", "INSTANT_MEETING", "INSTANT_MEETING_ACCEPTED", "RECORDING_TRANSCRIPTION_GENERATED", "OOO_CREATED", "AFTER_HOSTS_CAL_VIDEO_NO_SHOW", "AFTER_GUESTS_CAL_VIDEO_NO_SHOW", "FORM_SUBMITTED_NO_EVENT", "ROUTING_FORM_FALLBACK_HIT", "DELEGATION_CREDENTIAL_ERROR", "WRONG_ASSIGNMENT_REPORT", "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED", "DELEGATION_CREDENTIAL_ROTATION_REQUIRED", "DELEGATION_CREDENTIAL_SECRET_ROTATED", "CALENDAR_ENTRY_REJECTED", "CAL_EVENT_REGISTRATION_REQUESTED", "CAL_EVENT_REGISTRATION_CONFIRMED", "CAL_EVENT_REGISTRATION_WAITLISTED", "CAL_EVENT_REGISTRATION_DECLINED", "CAL_EVENT_REGISTRATION_CANCELLED" ] } }, "customHeaders": { "description": "Static headers sent on every delivery. Values are always redacted as `\"***\"`.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookCustomHeaderOutputDto" } }, "time": { "type": "number", "description": "How long after the booking start time the no-show triggers are evaluated", "example": 5 }, "timeUnit": { "enum": ["DAY", "HOUR", "MINUTE"], "type": "string", "description": "The unit of the no-show time value", "example": "MINUTE" }, "version": { "enum": ["2021-10-20", "2026-07-27"], "type": "string", "description": "The payload format version of the webhook. Version 2026-07-27 adds generated ICS calendar content (`attendeeIcsContent`, `organizerIcsContent`) to BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_SEAT_ACCEPTED, and BOOKING_PAID (when the payment accepted the booking) payloads. Every version's builder-produced payload carries a `payload.platformOAuthClientId` field naming the owning platform OAuth client (`null` for non-platform events; for the flat-delivered MEETING_STARTED/MEETING_ENDED bodies the field appears at the top level of the body). Zapier deliveries, custom payload templates that do not reference the field, the `AFTER_HOSTS_CAL_VIDEO_NO_SHOW` / `AFTER_GUESTS_CAL_VIDEO_NO_SHOW` bodies (delivered verbatim from the fire-time blob, never built) and the legacy `FORM_SUBMITTED_NO_EVENT` fallback delivery omit it.", "example": "2021-10-20" }, "oAuthClientId": { "type": "string" }, "id": { "type": "number" }, "subscriberUrl": { "type": "string" }, "active": { "type": "boolean" }, "secret": { "type": "string" } }, "required": [ "payloadTemplate", "triggers", "version", "oAuthClientId", "id", "subscriberUrl", "active" ] }, "OAuthClientWebhookOutputResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/OAuthClientWebhookOutputDto" } }, "required": ["status", "data"] }, "OAuthClientWebhooksOutputResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthClientWebhookOutputDto" } } }, "required": ["status", "data"] }, "DestinationCalendarsInputBodyDto": { "type": "object", "properties": { "integration": { "enum": ["apple_calendar", "google_calendar", "office365_calendar"], "type": "string", "example": "apple_calendar", "description": "The calendar service you want to integrate, as returned by the /calendars endpoint" }, "externalId": { "type": "string", "example": "https://caldav.icloud.com/26962146906/calendars/1644422A-1945-4438-BBC0-4F0Q23A57R7S/", "description": "Unique identifier used to represent the specific calendar, as returned by the /calendars endpoint" }, "delegationCredentialId": { "type": "string" } }, "required": ["integration", "externalId"] }, "DestinationCalendarsOutputDto": { "type": "object", "properties": { "userId": { "type": "number" }, "integration": { "type": "string" }, "externalId": { "type": "string" }, "credentialId": { "type": "number", "nullable": true } }, "required": ["userId", "integration", "externalId", "credentialId"] }, "DestinationCalendarsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DestinationCalendarsOutputDto" } }, "required": ["status", "data"] }, "BookingInsightsEventTrendDto": { "type": "object", "properties": { "formattedDateFull": { "type": "string", "description": "Full formatted date label for the data point", "example": "Jan 1, 2024" }, "isToday": { "type": "boolean", "description": "Whether this data point represents the current day", "example": false }, "Month": { "type": "string", "description": "Abbreviated month-day label for chart display", "example": "Jan 1" }, "Created": { "type": "number", "description": "Number of bookings created on this date", "example": 12 }, "Completed": { "type": "number", "description": "Number of bookings completed on this date", "example": 8 }, "Rescheduled": { "type": "number", "description": "Number of bookings rescheduled on this date", "example": 2 }, "Cancelled": { "type": "number", "description": "Number of bookings cancelled on this date", "example": 1 }, "No-Show (Host)": { "type": "number", "description": "Number of host no-shows on this date", "example": 0 }, "No-Show (Guest)": { "type": "number", "description": "Number of guest no-shows on this date", "example": 1 } }, "required": [ "formattedDateFull", "isToday", "Month", "Created", "Completed", "Rescheduled", "Cancelled", "No-Show (Host)", "No-Show (Guest)" ] }, "BookingInsightsAverageDurationDto": { "type": "object", "properties": { "Date": { "type": "string", "description": "Abbreviated date label for chart display", "example": "Jan 1" }, "formattedDateFull": { "type": "string", "description": "Full formatted date label for the data point", "example": "Jan 1, 2024" }, "isToday": { "type": "boolean", "description": "Whether this data point represents the current day", "example": false }, "Average": { "type": "number", "description": "Average booking duration in minutes for this date", "example": 30 } }, "required": ["Date", "formattedDateFull", "isToday", "Average"] }, "BookingInsightsMemberUserDto": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID of the team member", "example": 101 }, "username": { "type": "string", "nullable": true, "description": "Username of the team member", "example": "alice" }, "name": { "type": "string", "nullable": true, "description": "Display name of the team member", "example": "Alice" }, "email": { "type": "string", "description": "Email address of the team member", "example": "alice@example.com" }, "avatarUrl": { "type": "string", "nullable": true, "description": "Avatar image URL", "example": "/alice/avatar.png" } }, "required": ["id", "email"] }, "BookingInsightsMemberStatDto": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID of the team member", "example": 101 }, "user": { "description": "Team member profile details", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMemberUserDto" } ] }, "emailMd5": { "type": "string", "description": "MD5 hash of email for Gravatar lookup", "example": "c160f8cc69a4f0bf2b0362752353d060" }, "count": { "type": "number", "description": "Number of bookings for this ranking category", "example": 8 } }, "required": ["userId", "user", "emailMd5", "count"] }, "BookingInsightsMetricOutput": { "type": "object", "properties": { "count": { "type": "number", "description": "Metric value for the current period", "example": 10 }, "deltaPrevious": { "type": "number", "description": "Percentage change compared to the previous period", "example": 12.5 } }, "required": ["count", "deltaPrevious"] }, "BookingInsightsPreviousRangeOutput": { "type": "object", "properties": { "startDate": { "type": "string", "description": "Start date of the previous comparison period", "example": "Dec 1, 2023" }, "endDate": { "type": "string", "description": "End date of the previous comparison period", "example": "Dec 31, 2023" } }, "required": ["startDate", "endDate"] }, "BookingInsightsKpiStatsDataOutput": { "type": "object", "properties": { "empty": { "type": "boolean", "description": "Whether no data exists for the selected period", "example": false }, "created": { "description": "Total bookings created in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "scheduled": { "description": "Total bookings scheduled (upcoming) in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "completed": { "description": "Total bookings completed in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "rescheduled": { "description": "Total bookings rescheduled in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "cancelled": { "description": "Total bookings cancelled in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "no_show": { "description": "Total host no-shows in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "no_show_guest": { "description": "Total guest no-shows in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "rating": { "description": "Average rating score in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "csat": { "description": "Customer satisfaction percentage (0-100) in the period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMetricOutput" } ] }, "previousRange": { "description": "Date range of the previous comparison period", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsPreviousRangeOutput" } ] } }, "required": [ "empty", "created", "scheduled", "completed", "rescheduled", "cancelled", "no_show", "no_show_guest", "rating", "csat", "previousRange" ] }, "BookingInsightsMemberStatsDataOutput": { "type": "object", "properties": { "mostBookings": { "description": "Members ranked by most total bookings", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "leastBookings": { "description": "Members ranked by fewest total bookings", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "mostCancelled": { "description": "Members ranked by most cancellations", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "mostCompleted": { "description": "Members ranked by most completed bookings", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "leastCompleted": { "description": "Members ranked by fewest completed bookings", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "mostNoShow": { "description": "Members ranked by most no-shows", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "highestRatings": { "description": "Members ranked by highest average rating", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } }, "lowestRatings": { "description": "Members ranked by lowest average rating", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsMemberStatDto" } } }, "required": [ "mostBookings", "leastBookings", "mostCancelled", "mostCompleted", "leastCompleted", "mostNoShow", "highestRatings", "lowestRatings" ] }, "InsightsRoutingFormsByStatusDataOutput": { "type": "object", "properties": { "total": { "type": "number", "example": 100 }, "totalWithoutBooking": { "type": "number", "example": 25 }, "totalWithBooking": { "type": "number", "example": 75 } }, "required": ["total", "totalWithoutBooking", "totalWithBooking"] }, "InsightsRoutingBookingAttendeeOutput": { "type": "object", "properties": { "name": { "type": "string", "example": "Jane Doe" }, "timeZone": { "type": "string", "example": "Europe/London" }, "email": { "type": "string", "example": "jane@example.com" }, "phoneNumber": { "type": "string", "example": null, "nullable": true } }, "required": ["name", "timeZone", "email", "phoneNumber"] }, "InsightsRoutingResponseFieldOutput": { "type": "object", "properties": { "fieldId": { "type": "string", "example": "company-size", "nullable": true }, "valueString": { "type": "string", "example": "Enterprise", "nullable": true }, "valueNumber": { "type": "number", "example": 100, "nullable": true }, "valueStringArray": { "example": ["Enterprise", "Mid Market"], "nullable": true, "type": "array", "items": { "type": "string" } } }, "required": ["fieldId", "valueString", "valueNumber", "valueStringArray"] }, "InsightsRoutingFormResponseOutput": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "uuid": { "type": "string", "example": "form_123", "nullable": true }, "formId": { "type": "string", "example": "form_123" }, "formName": { "type": "string", "example": "Contact Sales" }, "formTeamId": { "type": "number", "example": 10, "nullable": true }, "formUserId": { "type": "number", "example": 101, "nullable": true }, "bookingUid": { "type": "string", "example": "booking_uid", "nullable": true }, "bookingId": { "type": "number", "example": 1, "nullable": true }, "bookingStatus": { "type": "string", "example": "ACCEPTED", "nullable": true }, "bookingStatusOrder": { "type": "number", "example": 1, "nullable": true }, "bookingCreatedAt": { "type": "string", "example": "2024-01-01T00:00:00.000Z", "nullable": true, "format": "date-time" }, "bookingUserId": { "type": "number", "example": 101, "nullable": true }, "bookingUserName": { "type": "string", "example": "Alice Doe", "nullable": true }, "bookingUserEmail": { "type": "string", "example": "alice@example.com", "nullable": true }, "bookingUserAvatarUrl": { "type": "string", "example": "https://example.com/avatar.png", "nullable": true }, "bookingAssignmentReason": { "type": "string", "example": "round_robin", "nullable": true }, "bookingStartTime": { "type": "string", "example": "2024-01-01T09:00:00.000Z", "nullable": true, "format": "date-time" }, "bookingEndTime": { "type": "string", "example": "2024-01-01T09:30:00.000Z", "nullable": true, "format": "date-time" }, "eventTypeId": { "type": "number", "example": 200, "nullable": true }, "eventTypeParentId": { "type": "number", "example": null, "nullable": true }, "eventTypeSchedulingType": { "type": "string", "example": "ROUND_ROBIN", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-01-01T00:00:00.000Z" }, "utm_source": { "type": "string", "example": "google", "nullable": true }, "utm_medium": { "type": "string", "example": "cpc", "nullable": true }, "utm_campaign": { "type": "string", "example": "spring_launch", "nullable": true }, "utm_term": { "type": "string", "example": "calendar scheduling", "nullable": true }, "utm_content": { "type": "string", "example": "hero_cta", "nullable": true }, "bookingAttendees": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingBookingAttendeeOutput" } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingResponseFieldOutput" } } }, "required": [ "id", "uuid", "formId", "formName", "formTeamId", "formUserId", "bookingUid", "bookingId", "bookingStatus", "bookingStatusOrder", "bookingCreatedAt", "bookingUserId", "bookingUserName", "bookingUserEmail", "bookingUserAvatarUrl", "bookingAssignmentReason", "bookingStartTime", "bookingEndTime", "eventTypeId", "eventTypeParentId", "eventTypeSchedulingType", "createdAt", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "bookingAttendees", "fields" ] }, "InsightsRoutingFormResponsesDataOutput": { "type": "object", "properties": { "total": { "type": "number", "example": 10 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingFormResponseOutput" } } }, "required": ["total", "data"] }, "InsightsRoutingFormFieldOptionOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "option_1", "nullable": true }, "label": { "type": "string", "example": "Enterprise" } }, "required": ["id", "label"] }, "InsightsRoutingFormFieldOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "field_1" }, "label": { "type": "string", "example": "Company size" }, "type": { "type": "string", "example": "select" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingFormFieldOptionOutput" } } }, "required": ["id", "label"] }, "InsightsRoutingRoutedToUserOutput": { "type": "object", "properties": { "id": { "type": "number", "example": 101 }, "name": { "type": "string", "example": "Alice Doe", "nullable": true }, "email": { "type": "object", "example": "alice@example.com", "nullable": true }, "avatarUrl": { "type": "object", "example": "https://example.com/avatar.png", "nullable": true }, "performance": { "type": "string", "example": "above_average" }, "totalBookings": { "type": "number", "example": 12 } }, "required": ["id", "name", "email", "avatarUrl", "performance", "totalBookings"] }, "InsightsRoutingRoutedToPeriodStatOutput": { "type": "object", "properties": { "userId": { "type": "number", "example": 101 }, "period_start": { "format": "date-time", "type": "string", "example": "2024-01-01T00:00:00.000Z" }, "total": { "type": "number", "example": 3 } }, "required": ["userId", "period_start", "total"] }, "InsightsRoutingRoutedToUsersOutput": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingRoutedToUserOutput" } } }, "required": ["data"] }, "InsightsRoutingRoutedToPeriodStatsOutput": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingRoutedToPeriodStatOutput" } } }, "required": ["data"] }, "InsightsRoutingRoutedToPerPeriodDataOutput": { "type": "object", "properties": { "users": { "$ref": "#/components/schemas/InsightsRoutingRoutedToUsersOutput" }, "periodStats": { "$ref": "#/components/schemas/InsightsRoutingRoutedToPeriodStatsOutput" } }, "required": ["users", "periodStats"] }, "BookingLimitPeriodUsageOutput": { "type": "object", "properties": { "limit": { "type": "number", "example": 20, "description": "The configured maximum for this period." }, "used": { "type": "number", "example": 7, "description": "Accepted bookings counted against the limit in this period." }, "remaining": { "type": "number", "example": 13, "description": "Bookings left in this period, never below 0." }, "periodStart": { "type": "string", "example": "2026-10-11", "description": "First day of the period (YYYY-MM-DD) in `timeZone`." }, "periodEnd": { "type": "string", "example": "2026-10-17", "description": "Last day of the period (YYYY-MM-DD, inclusive) in `timeZone`." } }, "required": ["limit", "used", "remaining", "periodStart", "periodEnd"] }, "BookingLimitPeriodsUsageOutput": { "type": "object", "properties": { "perDay": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "perWeek": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "perMonth": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "perYear": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] } }, "required": ["perDay", "perWeek", "perMonth", "perYear"] }, "EventTypeBookingLimitsUsageOutput": { "type": "object", "properties": { "perDay": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "perWeek": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "perMonth": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "perYear": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodUsageOutput" } ] }, "eventTypeId": { "type": "number", "example": 101 }, "timeZone": { "type": "string", "example": "Europe/London", "description": "Time zone the event type's periods are counted in." } }, "required": ["perDay", "perWeek", "perMonth", "perYear", "eventTypeId", "timeZone"] }, "BindingBookingLimitOutput": { "type": "object", "properties": { "layer": { "type": "string", "enum": ["eventType", "user"], "example": "user" }, "limitKey": { "type": "string", "enum": ["perDay", "perWeek", "perMonth", "perYear"], "example": "perWeek" }, "remaining": { "type": "number", "example": 2 } }, "required": ["layer", "limitKey", "remaining"] }, "UserBookingLimitsUsageOutput": { "type": "object", "properties": { "userUuid": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }, "timeZone": { "type": "string", "example": "America/New_York", "description": "Time zone the user's own periods are counted in." }, "user": { "description": "The user's global booking limit.", "allOf": [ { "$ref": "#/components/schemas/BookingLimitPeriodsUsageOutput" } ] }, "binding": { "nullable": true, "description": "The limit with the least room left across the event type's limit and the user's global limit; null when neither applies. Team booking limits are not included yet.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BindingBookingLimitOutput" } ] } }, "required": ["userUuid", "timeZone", "user", "binding"] }, "BookingLimitsUsageDataOutput": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-10-13", "description": "The requested calendar day; null when the periods containing today were reported." }, "eventType": { "nullable": true, "description": "Shared by every host of the event type; null when no eventTypeId was given.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventTypeBookingLimitsUsageOutput" } ] }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserBookingLimitsUsageOutput" } }, "total": { "type": "number", "example": 42, "description": "Users in scope, before paging." } }, "required": ["date", "eventType", "users", "total"] }, "BookingLimitsUsageInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["user", "team", "org"], "example": "team", "description": "`user`: the caller only. `team`: accepted members of `selectedTeamId`. `org`: the hosts of `eventTypeId`, which is then required." }, "selectedTeamId": { "type": "number", "description": "Required for team scope.", "example": 12 }, "date": { "type": "string", "description": "Calendar day (YYYY-MM-DD). Reports the day, week, month and year containing it, each read in its limit's own time zone: the user's for the global limit, the event type's for the event-type limit. Defaults to today.", "example": "2026-10-13" }, "eventTypeId": { "description": "Adds the event type's own booking limit. Accepts a numeric ID or UUID. Must be an event type inside the scope; required for org scope.", "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ], "example": 101 }, "userUuids": { "description": "Only report these users. Every uuid must be inside the scope.", "maxItems": 100, "example": ["3f2504e0-4f89-41d3-9a0c-0305e82c3301"], "type": "array", "items": { "type": "string" } }, "offset": { "type": "number", "example": 0 }, "limit": { "type": "number", "example": 50, "maximum": 100 } }, "required": ["scope", "offset", "limit"] }, "GetBookingLimitsUsageOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/BookingLimitsUsageDataOutput" } }, "required": ["status", "data"] }, "BookingInsightsInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["user", "team", "org"], "example": "user" }, "selectedTeamId": { "type": "number", "description": "Team ID for team-scoped insights", "example": 12 }, "timeZone": { "type": "string", "description": "IANA timezone used to group time-series insights", "example": "America/New_York" }, "columnFilters": { "type": "array", "description": "Data-table column filters (discriminated union by type: ss, ms, t, n, dr). Date range filters use id=startTime or id=createdAt.", "example": [ { "id": "createdAt", "value": { "type": "dr", "data": { "startDate": "2024-01-01", "endDate": "2024-01-31", "preset": "custom" } } } ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column identifier" }, "value": { "type": "object", "description": "Filter value discriminated by type field", "properties": { "type": { "type": "string", "enum": ["ss", "ms", "t", "n", "dr"] }, "data": { "type": "object" } } } } } } }, "required": ["scope", "timeZone"] }, "GetBookingKpiStatsOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success", "enum": ["success", "error"] }, "data": { "description": "KPI statistics data", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsKpiStatsDataOutput" } ] } }, "required": ["status", "data"] }, "GetBookingEventTrendsOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success", "enum": ["success", "error"] }, "data": { "description": "Array of daily event trend data points", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsEventTrendDto" } } }, "required": ["status", "data"] }, "GetBookingAverageDurationOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success", "enum": ["success", "error"] }, "data": { "description": "Array of daily average duration data points", "type": "array", "items": { "$ref": "#/components/schemas/BookingInsightsAverageDurationDto" } } }, "required": ["status", "data"] }, "GetBookingMemberStatsOutput": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success", "enum": ["success", "error"] }, "data": { "description": "Member statistics grouped by ranking category", "allOf": [ { "$ref": "#/components/schemas/BookingInsightsMemberStatsDataOutput" } ] } }, "required": ["status", "data"] }, "RoutingInsightsBaseInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["user", "team", "org"], "example": "user" }, "selectedTeamId": { "type": "number", "description": "Team ID for team-scoped routing insights", "example": 12 }, "startDate": { "type": "string", "description": "Inclusive start date for routing insights", "example": "2024-01-01" }, "endDate": { "type": "string", "description": "Inclusive end date for routing insights", "example": "2024-01-31" }, "columnFilters": { "type": "array", "description": "Data-table column filters (discriminated union by type: ss, ms, t, n, dr). Date range filters use id=createdAt.", "example": [ { "id": "createdAt", "value": { "type": "dr", "data": { "startDate": "2024-01-01", "endDate": "2024-01-31", "preset": "custom" } } } ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": ["ss", "ms", "t", "n", "dr"] }, "data": { "type": "object" } } } } } } }, "required": ["scope", "startDate", "endDate"] }, "GetInsightsRoutingFormsByStatusOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InsightsRoutingFormsByStatusDataOutput" } ] } }, "required": ["status", "data"] }, "RoutingInsightsPaginatedInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["user", "team", "org"], "example": "user" }, "selectedTeamId": { "type": "number", "description": "Team ID for team-scoped routing insights", "example": 12 }, "startDate": { "type": "string", "description": "Inclusive start date for routing insights", "example": "2024-01-01" }, "endDate": { "type": "string", "description": "Inclusive end date for routing insights", "example": "2024-01-31" }, "columnFilters": { "type": "array", "description": "Data-table column filters (discriminated union by type: ss, ms, t, n, dr). Date range filters use id=createdAt.", "example": [ { "id": "createdAt", "value": { "type": "dr", "data": { "startDate": "2024-01-01", "endDate": "2024-01-31", "preset": "custom" } } } ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": ["ss", "ms", "t", "n", "dr"] }, "data": { "type": "object" } } } } } }, "sorting": { "type": "array", "example": [ { "id": "createdAt", "desc": true } ] }, "offset": { "type": "number", "example": 0 }, "limit": { "type": "number", "example": 50, "maximum": 100 } }, "required": ["scope", "startDate", "endDate", "offset", "limit"] }, "GetInsightsRoutingFormResponsesOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/InsightsRoutingFormResponsesDataOutput" } }, "required": ["status", "data"] }, "RoutingFormFieldsInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["user", "team", "org"], "example": "user" }, "selectedTeamId": { "type": "number", "description": "Team ID for team-scoped routing insights", "example": 12 }, "routingFormId": { "type": "string", "description": "Routing form ID to filter fields", "example": "form_123" } }, "required": ["scope"] }, "GetInsightsRoutingFormFieldOptionsOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingFormFieldOutput" } } }, "required": ["status", "data"] }, "GetInsightsRoutingFormHeadersOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightsRoutingFormFieldOutput" } } }, "required": ["status", "data"] }, "GetInsightsRoutingFailedBookingsByFieldOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "type": "object", "example": { "Contact Sales": { "Company size": [ { "optionId": "option_1", "optionLabel": "Enterprise", "count": 5 } ] } } } }, "required": ["status", "data"] }, "RoutedToPerPeriodInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["user", "team", "org"], "example": "user" }, "selectedTeamId": { "type": "number", "description": "Team ID for team-scoped routing insights", "example": 12 }, "startDate": { "type": "string", "description": "Inclusive start date for routing insights", "example": "2024-01-01" }, "endDate": { "type": "string", "description": "Inclusive end date for routing insights", "example": "2024-01-31" }, "columnFilters": { "type": "array", "description": "Data-table column filters (discriminated union by type: ss, ms, t, n, dr). Date range filters use id=createdAt.", "example": [ { "id": "createdAt", "value": { "type": "dr", "data": { "startDate": "2024-01-01", "endDate": "2024-01-31", "preset": "custom" } } } ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": ["ss", "ms", "t", "n", "dr"] }, "data": { "type": "object" } } } } } }, "period": { "type": "string", "enum": ["perDay", "perWeek", "perMonth"], "example": "perWeek" }, "limit": { "type": "number", "example": 10, "maximum": 100 }, "searchQuery": { "type": "string", "example": "Alice" } }, "required": ["scope", "startDate", "endDate", "period", "limit"] }, "GetInsightsRoutingRoutedToPerPeriodOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "data": { "$ref": "#/components/schemas/InsightsRoutingRoutedToPerPeriodDataOutput" } }, "required": ["status", "data"] }, "SendVerificationEmailInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "username": { "type": "string", "example": "johndoe" }, "language": { "type": "string", "example": "en" }, "isVerifyingEmail": { "type": "boolean", "example": true }, "eventTypeId": { "type": "number", "example": 123, "description": "Id of the event type being booked. When provided, the email honours the hide-branding setting of the event type's owner or team." } }, "required": ["email"] }, "SendVerificationEmailData": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true } }, "required": ["sent"] }, "SendVerificationEmailOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SendVerificationEmailData" } }, "required": ["status", "data"] }, "VerifyEmailCodeInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "code": { "type": "string", "example": "123456" } }, "required": ["email", "code"] }, "VerifyEmailCodeData": { "type": "object", "properties": { "verified": { "type": "boolean", "example": true } }, "required": ["verified"] }, "VerifyEmailCodeOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/VerifyEmailCodeData" } }, "required": ["status", "data"] }, "CalendarEventVideoLocation": { "type": "object", "properties": { "type": { "type": "string", "default": "video", "enum": ["video"], "description": "Indicates this is a video conference location" }, "url": { "type": "string", "description": "URL for joining the video conference" }, "label": { "type": "string", "nullable": true, "description": "Display name for the video conference" }, "password": { "type": "string", "nullable": true, "description": "Password required to join the video conference" }, "meetingCode": { "type": "string", "nullable": true, "description": "Meeting code or ID required to join the conference" }, "accessCode": { "type": "string", "nullable": true, "description": "Access code required to join the conference" } }, "required": ["type", "url"] }, "CalendarEventPhoneLocation": { "type": "object", "properties": { "type": { "type": "string", "default": "phone", "enum": ["phone"], "description": "Indicates this is a phone conference location" }, "url": { "type": "string", "description": "Phone number or URL for dialing into the conference" }, "label": { "type": "string", "nullable": true, "description": "Display name for the phone conference" }, "pin": { "type": "string", "nullable": true, "description": "PIN number required for the phone conference" }, "password": { "type": "string", "nullable": true, "description": "Password required for the phone conference" }, "accessCode": { "type": "string", "nullable": true, "description": "Access code required for the phone conference" }, "regionCode": { "type": "string", "nullable": true, "description": "Country/region code for the phone number" } }, "required": ["type", "url"] }, "CalendarEventSipLocation": { "type": "object", "properties": { "type": { "type": "string", "default": "sip", "enum": ["sip"], "description": "Indicates this is a SIP (Session Initiation Protocol) conference location" }, "url": { "type": "string", "description": "SIP URL for joining the conference" }, "label": { "type": "string", "nullable": true, "description": "Display name for the SIP conference" }, "pin": { "type": "string", "nullable": true, "description": "PIN number required for the SIP conference" }, "password": { "type": "string", "nullable": true, "description": "Password required for the SIP conference" } }, "required": ["type", "url"] }, "CalendarEventMoreLocation": { "type": "object", "properties": { "type": { "type": "string", "default": "more", "enum": ["more"], "description": "Indicates this is an additional conference location type" }, "url": { "type": "string", "description": "URL for accessing this location" }, "label": { "type": "string", "nullable": true, "description": "Display name for this location" } }, "required": ["type", "url"] }, "CalendarEventResponseStatus": { "type": "string", "enum": ["accepted", "pending", "declined", "needsAction"], "description": "Attendee's response to the invitation" }, "CalendarEventAttendee": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the attendee" }, "name": { "type": "string", "description": "Display name of the attendee" }, "responseStatus": { "nullable": true, "description": "Attendee's response to the invitation", "example": "accepted", "allOf": [ { "$ref": "#/components/schemas/CalendarEventResponseStatus" } ] }, "self": { "type": "boolean", "nullable": true, "description": "Indicates if this attendee is the current user" }, "optional": { "type": "boolean", "nullable": true, "description": "Indicates if this attendee's attendance is optional" }, "host": { "type": "boolean", "nullable": true, "description": "Indicates if this attendee is the host" } }, "required": ["email"] }, "CalendarEventStatus": { "type": "string", "enum": ["accepted", "pending", "declined", "cancelled"], "description": "Status of the event (accepted, pending, declined, cancelled)" }, "CalendarEventHost": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the event host" }, "name": { "type": "string", "nullable": true, "description": "Display name of the event host" }, "responseStatus": { "nullable": true, "description": "Host's response to the invitation", "example": "accepted", "allOf": [ { "$ref": "#/components/schemas/CalendarEventResponseStatus" } ] } }, "required": ["email"] }, "calendarEventOwner": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the event host" }, "name": { "type": "string", "nullable": true, "description": "Display name of the event host" } }, "required": ["email"] }, "CalendarSource": { "type": "string", "enum": ["google", "office365", "apple"], "description": "Calendar integration source (e.g., Google Calendar, Office 365, Apple Calendar). Currently only Google Calendar is supported." }, "UnifiedCalendarEventOutput": { "type": "object", "properties": { "start": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" } }, "description": "Start date and time of the calendar event with timezone information" }, "end": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" } }, "description": "End date and time of the calendar event with timezone information" }, "id": { "type": "string", "description": "Unique identifier of the calendar event" }, "title": { "type": "string", "description": "Title of the calendar event" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the calendar event" }, "locations": { "type": "array", "items": { "oneOf": [ { "title": "Video", "$ref": "#/components/schemas/CalendarEventVideoLocation" }, { "title": "Phone", "$ref": "#/components/schemas/CalendarEventPhoneLocation" }, { "title": "SIP", "$ref": "#/components/schemas/CalendarEventSipLocation" }, { "title": "More", "$ref": "#/components/schemas/CalendarEventMoreLocation" } ], "discriminator": { "propertyName": "type" } }, "nullable": true, "description": "Conference locations with entry points (video, phone, sip, more)" }, "attendees": { "nullable": true, "description": "List of attendees with their response status", "type": "array", "items": { "$ref": "#/components/schemas/CalendarEventAttendee" } }, "status": { "nullable": true, "description": "Status of the event (accepted, pending, declined, cancelled)", "example": "accepted", "allOf": [ { "$ref": "#/components/schemas/CalendarEventStatus" } ] }, "hosts": { "nullable": true, "description": "Information about the event hosts (organizers)", "type": "array", "items": { "$ref": "#/components/schemas/CalendarEventHost" } }, "calendarEventOwner": { "nullable": true, "description": "The calendar account that owns this event. This is the primary calendar where the event is stored and cannot be modified without appropriate permissions. Changing this would require moving the event to a different calendar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/calendarEventOwner" } ] }, "source": { "description": "Calendar integration source (e.g., Google Calendar, Office 365, Apple Calendar). Currently only Google Calendar is supported.", "example": "google", "allOf": [ { "$ref": "#/components/schemas/CalendarSource" } ] } }, "required": ["start", "end", "id", "title", "source"] }, "GetUnifiedCalendarEventOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UnifiedCalendarEventOutput" } }, "required": ["status", "data"] }, "UpdateCalendarEventAttendee": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the attendee" }, "name": { "type": "string", "description": "Display name of the attendee" }, "responseStatus": { "nullable": true, "description": "Response status of the attendee", "allOf": [ { "$ref": "#/components/schemas/CalendarEventResponseStatus" } ] }, "self": { "type": "boolean", "nullable": true, "description": "Indicates if this attendee is the current user" }, "optional": { "type": "boolean", "nullable": true, "description": "Indicates if this attendee's attendance is optional" }, "host": { "type": "boolean", "nullable": true, "description": "Indicates if this attendee is the host" } } }, "UpdateUnifiedCalendarEventInput": { "type": "object", "properties": { "start": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" } }, "description": "Start date and time of the calendar event with timezone information" }, "end": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" } }, "description": "End date and time of the calendar event with timezone information" }, "title": { "type": "string", "description": "Title of the calendar event" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the calendar event" }, "attendees": { "nullable": true, "description": "List of attendees. CAUTION: You must pass the entire array with all updated values. Any attendees not included in this array will be removed from the event.", "type": "array", "items": { "$ref": "#/components/schemas/UpdateCalendarEventAttendee" } }, "status": { "nullable": true, "description": "Status of the event (accepted, pending, declined, cancelled)", "example": "accepted", "allOf": [ { "$ref": "#/components/schemas/CalendarEventStatus" } ] } } }, "EventAddressLocationOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of this location. Pass it to `PATCH` or `DELETE /v2/events/{uuid}/locations/{locationId}` to edit or remove this location." }, "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "example": 2500, "description": "Price a guest who picks this location pays, in the currency's smallest unit. null when the location is free." }, "currency": { "type": "string", "nullable": true, "example": "usd", "description": "Currency of price. null when the location is free." }, "capacity": { "type": "number", "description": "Seats at this location. Absent when unlimited.", "minimum": 1, "maximum": 100000 }, "type": { "type": "string", "example": "address", "enum": ["address"] }, "address": { "type": "string", "example": "123 Event Street" } }, "required": ["id", "price", "currency", "type", "address"] }, "EventLinkLocationOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of this location. Pass it to `PATCH` or `DELETE /v2/events/{uuid}/locations/{locationId}` to edit or remove this location." }, "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "example": 2500, "description": "Price a guest who picks this location pays, in the currency's smallest unit. null when the location is free." }, "currency": { "type": "string", "nullable": true, "example": "usd", "description": "Currency of price. null when the location is free." }, "capacity": { "type": "number", "description": "Seats at this location. Absent when unlimited.", "minimum": 1, "maximum": 100000 }, "type": { "type": "string", "example": "link", "enum": ["link"] }, "link": { "type": "string", "example": "https://example.com/event" } }, "required": ["id", "price", "currency", "type", "link"] }, "EventIntegrationLocationOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of this location. Pass it to `PATCH` or `DELETE /v2/events/{uuid}/locations/{locationId}` to edit or remove this location." }, "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "example": 2500, "description": "Price a guest who picks this location pays, in the currency's smallest unit. null when the location is free." }, "currency": { "type": "string", "nullable": true, "example": "usd", "description": "Currency of price. null when the location is free." }, "capacity": { "type": "number", "description": "Seats at this location. Absent when unlimited.", "minimum": 1, "maximum": 100000 }, "type": { "type": "string", "example": "integration", "enum": ["integration"] }, "integration": { "type": "string", "description": "The integration's API name, e.g. `zoom` or `google-meet`. An app without an API name is returned with its stored type, e.g. `integrations:dialpad_video`.", "example": "zoom" }, "credentialId": { "type": "number", "description": "Identifies which connected account will host the Event when a host has multiple connected accounts." } }, "required": ["id", "price", "currency", "type", "integration"] }, "EventOrganizersDefaultAppLocationOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of this location. Pass it to `PATCH` or `DELETE /v2/events/{uuid}/locations/{locationId}` to edit or remove this location." }, "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "example": 2500, "description": "Price a guest who picks this location pays, in the currency's smallest unit. null when the location is free." }, "currency": { "type": "string", "nullable": true, "example": "usd", "description": "Currency of price. null when the location is free." }, "capacity": { "type": "number", "description": "Seats at this location. Absent when unlimited.", "minimum": 1, "maximum": 100000 }, "type": { "type": "string", "example": "organizersDefaultApp", "enum": ["organizersDefaultApp"] } }, "required": ["id", "price", "currency", "type"] }, "EventUnknownLocationOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of this location. Pass it to `PATCH` or `DELETE /v2/events/{uuid}/locations/{locationId}` to edit or remove this location." }, "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "example": 2500, "description": "Price a guest who picks this location pays, in the currency's smallest unit. null when the location is free." }, "currency": { "type": "string", "nullable": true, "example": "usd", "description": "Currency of price. null when the location is free." }, "capacity": { "type": "number", "description": "Seats at this location. Absent when unlimited.", "minimum": 1, "maximum": 100000 }, "type": { "type": "string", "example": "unknown", "enum": ["unknown"] }, "location": { "type": "string", "description": "The stored location as JSON, for a location this API version can't represent. Remove it with `DELETE /v2/events/{uuid}/locations/{locationId}`." } }, "required": ["id", "price", "currency", "type", "location"] }, "EventLiveStreamOutput": { "type": "object", "properties": { "url": { "type": "string", "description": "Where people can watch the event live." } }, "required": ["url"] }, "EventPosterPaletteOutput": { "type": "object", "properties": { "background": { "type": "string", "description": "Background hex color.", "example": "#0b1c2c" }, "foreground": { "type": "string", "description": "Foreground hex color.", "example": "#a5d8ff" }, "accent": { "type": "string", "description": "Accent hex color.", "example": "#1f6feb" } }, "required": ["background", "foreground", "accent"] }, "EventPosterOutput": { "type": "object", "properties": { "layout": { "enum": ["date", "bauhaus", "rings", "waves", "halftone", "split"], "type": "string" }, "palette": { "$ref": "#/components/schemas/EventPosterPaletteOutput" }, "headline": { "type": "string", "nullable": true }, "seed": { "type": "number" } }, "required": ["layout", "palette", "headline", "seed"] }, "EventLineupPersonLinkOutput": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }, "EventLineupPersonMediaOutput": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string", "nullable": true } }, "required": ["url", "label"] }, "EventLineupPersonOutput": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/EventLineupPersonLinkOutput" } }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/EventLineupPersonMediaOutput" } } }, "required": ["name", "role", "avatarUrl", "links", "media"] }, "EventLineupOutput": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/EventLineupPersonOutput" } } }, "required": ["title", "people"] }, "EventSchedulePersonLinkOutput": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }, "EventSchedulePersonOutput": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/EventSchedulePersonLinkOutput" } } }, "required": ["name", "role", "avatarUrl", "links"] }, "EventScheduleItemOutput": { "type": "object", "properties": { "startTime": { "format": "date-time", "type": "string", "nullable": true }, "endTime": { "format": "date-time", "type": "string", "nullable": true }, "timeLabel": { "type": "string", "nullable": true }, "content": { "type": "string" }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/EventSchedulePersonOutput" } } }, "required": ["startTime", "endTime", "timeLabel", "content", "people"] }, "EventBackgroundOutput": { "type": "object", "properties": { "effect": { "enum": [ "aurora", "tide", "satin", "resonance", "veil", "facet", "lumen", "contour", "recess", "halftone", "strata" ], "type": "string" }, "colors": { "type": "array", "items": { "type": "string" } } }, "required": ["effect", "colors"] }, "EventHostOutput": { "type": "object", "properties": { "userId": { "type": "number", "example": 123 }, "name": { "type": "string", "example": "Jane Doe", "description": "Empty string when the host has no name." }, "username": { "type": "string", "example": "jane", "description": "Empty string when the host has no username." }, "avatarUrl": { "type": "string", "description": "Empty string when the host has no avatar." } }, "required": ["userId", "name", "username", "avatarUrl"] }, "EventOutputDto": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the Event." }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "startTime": { "format": "date-time", "type": "string" }, "endTime": { "format": "date-time", "type": "string" }, "checkInOpensAt": { "format": "date-time", "type": "string", "description": "When hosts can start checking guests in: 12 hours before `startTime`." }, "checkInClosesAt": { "format": "date-time", "type": "string", "description": "When check-in closes: 12 hours after `endTime`." }, "timeZone": { "type": "string" }, "visibility": { "enum": ["PUBLIC", "UNLISTED"], "type": "string" }, "category": { "enum": ["meetup", "conference", "music", "sports"], "type": "string", "description": "What kind of event it is." }, "hidden": { "type": "boolean" }, "publishedAt": { "format": "date-time", "type": "string", "nullable": true }, "cancelledAt": { "format": "date-time", "type": "string", "nullable": true }, "status": { "type": "string", "description": "Lifecycle status that summarises hidden, publishedAt and cancelledAt: cancelled when the Event was cancelled, published once published, draft otherwise.", "enum": ["draft", "published", "cancelled"] }, "locations": { "type": "array", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/EventAddressLocationOutput" }, { "title": "Link", "$ref": "#/components/schemas/EventLinkLocationOutput" }, { "title": "Integration", "$ref": "#/components/schemas/EventIntegrationLocationOutput" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/EventOrganizersDefaultAppLocationOutput" }, { "title": "Unknown", "$ref": "#/components/schemas/EventUnknownLocationOutput" } ] } }, "coverImageUrl": { "type": "string", "nullable": true }, "requiresApproval": { "type": "boolean" }, "paymentTimeoutMinutes": { "type": "number", "nullable": true, "description": "How many minutes a guest's seat is held while they pay. null uses the default of 10 minutes." }, "registrationOpensAt": { "format": "date-time", "type": "string", "nullable": true, "description": "When guests can start registering. null means registration opens when the Event is published." }, "registrationClosesAt": { "format": "date-time", "type": "string", "nullable": true, "description": "When registration closes. null means registration closes when the Event starts." }, "waitlistEnabled": { "type": "boolean", "description": "Whether guests can join a waitlist when the Event is full. The waitlist only opens when the Event or the chosen location is full, so it only works when capacity is set on the Event or on a location." }, "showOrganizerEmail": { "type": "boolean", "description": "Whether guests can see the organizer's email." }, "guestList": { "enum": ["hidden", "names", "count"], "type": "string", "description": "Who guests can see on the Event's page: their names, only the count, or neither." }, "showPresentedBy": { "type": "boolean", "description": "Whether the Event shows who it is presented by." }, "confirmedCount": { "type": "number", "description": "Confirmed guest count. Returned when listing Events and omitted when fetching a single Event by uuid." }, "liveStreams": { "description": "Links where people can watch the event live, in display order.", "type": "array", "items": { "$ref": "#/components/schemas/EventLiveStreamOutput" } }, "theme": { "nullable": true, "enum": ["light", "dark"], "type": "string", "description": "Default theme of the event page; null follows the visitor's system setting." }, "poster": { "nullable": true, "description": "Poster cover design. The web app draws `coverImageUrl` from it. null when the cover is an uploaded image.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventPosterOutput" } ] }, "lineup": { "nullable": true, "description": "Speakers or performers on the event page. Returned on single-Event responses, not on Event lists.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventLineupOutput" } ] }, "schedule": { "nullable": true, "description": "Agenda on the event page. Returned on single-Event responses, not on Event lists.", "type": "array", "items": { "$ref": "#/components/schemas/EventScheduleItemOutput" } }, "background": { "nullable": true, "description": "Animated background of the event page.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventBackgroundOutput" } ] }, "registrationFields": { "type": "array", "description": "Questions guests answer when registering. Always includes name and email.", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] } }, "hosts": { "description": "Ordered host roster, creator first. External co-hosts are not included.", "type": "array", "items": { "$ref": "#/components/schemas/EventHostOutput" } }, "capacity": { "type": "number", "nullable": true, "description": "The most guests the Event can take; null when unlimited. Once any location has its own `capacity`, this is the sum of the location capacities, or null if any location has none. The waitlist only opens when the Event or the chosen location is full, so it only works when capacity is set on the Event or on a location.", "example": 100 }, "price": { "type": "number", "nullable": true, "description": "Price of an Event without locations, in the currency's smallest unit; null when free. Events with locations are priced per location.", "example": 1500 }, "currency": { "type": "string", "nullable": true, "description": "Cal Pay currency code of `price`.", "example": "usd" }, "paymentsEnabled": { "type": "boolean", "description": "Whether paid Events are available. When false, setting `price` on the Event or a location returns a 400.", "example": true }, "cancellationReason": { "type": "string", "nullable": true }, "userId": { "type": "number", "nullable": true, "description": "Owner user id for a personal Event; null for a team-owned one." }, "teamId": { "type": "number", "nullable": true, "description": "Owning team id for a team-owned Event; null for a personal one." } }, "required": [ "uuid", "slug", "title", "startTime", "endTime", "checkInOpensAt", "checkInClosesAt", "timeZone", "visibility", "category", "hidden", "status", "locations", "requiresApproval", "registrationOpensAt", "registrationClosesAt", "waitlistEnabled", "showOrganizerEmail", "guestList", "showPresentedBy", "liveStreams", "registrationFields", "hosts", "paymentsEnabled" ] }, "EventsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventOutputDto" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "EventsCursorPaginationMetaDto": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor to fetch the next page. Pass this value as the `cursor` query parameter on the next request. `null` when `hasMore` is `false`.", "example": "eyJ2IjoyLCJzdGFydFRpbWUiOiIyMDMwLTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJldmVudFR5cGVVdWlkIjoiMDE4ZjRjMmUtM2YxYS03YWJjLTlkZWYtMDEyMzQ1Njc4OWFiIn0" }, "hasMore": { "type": "boolean", "description": "Whether more pages are available after this one.", "example": true } }, "required": ["nextCursor", "hasMore"] }, "EventsCursorOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventOutputDto" } }, "pagination": { "$ref": "#/components/schemas/EventsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "EventAddressLocationInput": { "type": "object", "properties": { "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "minimum": 1, "description": "Price for this location, in the currency's smallest unit.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required when `price` is set.", "example": "usd" }, "capacity": { "type": "number", "minimum": 1, "description": "Seats at this location. Omit for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "address", "enum": ["address"] }, "address": { "type": "string", "minLength": 1, "example": "1 Example Street, Berlin" } }, "required": ["type", "address"] }, "EventLinkLocationInput": { "type": "object", "properties": { "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "minimum": 1, "description": "Price for this location, in the currency's smallest unit.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required when `price` is set.", "example": "usd" }, "capacity": { "type": "number", "minimum": 1, "description": "Seats at this location. Omit for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "link", "enum": ["link"] }, "link": { "type": "string", "format": "uri", "example": "https://example.com/watch" } }, "required": ["type", "link"] }, "EventIntegrationLocationInput": { "type": "object", "properties": { "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "minimum": 1, "description": "Price for this location, in the currency's smallest unit.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required when `price` is set.", "example": "usd" }, "capacity": { "type": "number", "minimum": 1, "description": "Seats at this location. Omit for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "integration", "enum": ["integration"] }, "integration": { "enum": [ "cal-video", "google-meet", "zoom", "whereby-video", "whatsapp-video", "webex-video", "telegram-video", "tandem", "sylaps-video", "skype-video", "sirius-video", "signal-video", "shimmer-video", "salesroom-video", "roam-video", "riverside-video", "ping-video", "office365-video", "mirotalk-video", "jitsi", "jelly-video", "jelly-conferencing", "huddle", "facetime-video", "element-call-video", "eightxeight-video", "discord-video", "demodesk-video", "campfire-video" ], "type": "string", "example": "cal-video" }, "credentialId": { "type": "number", "description": "Identifies which connected account will host the Event when a host has multiple connected accounts." } }, "required": ["type", "integration"] }, "EventOrganizersDefaultAppLocationInput": { "type": "object", "properties": { "label": { "type": "string", "description": "Name shown for this location.", "maxLength": 100 }, "price": { "type": "number", "minimum": 1, "description": "Price for this location, in the currency's smallest unit.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required when `price` is set.", "example": "usd" }, "capacity": { "type": "number", "minimum": 1, "description": "Seats at this location. Omit for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "organizersDefaultApp", "enum": ["organizersDefaultApp"] } }, "required": ["type"] }, "EventBackgroundInput": { "type": "object", "properties": { "effect": { "enum": [ "aurora", "tide", "satin", "resonance", "veil", "facet", "lumen", "contour", "recess", "halftone", "strata" ], "type": "string", "description": "Which animated effect renders." }, "colors": { "minItems": 3, "maxItems": 3, "description": "Exactly three hex colors the effect is drawn with.", "example": ["#0b1c2c", "#1f6feb", "#a5d8ff"], "type": "array", "items": { "type": "string", "pattern": "^#[0-9a-f]{6}$" } } }, "required": ["effect", "colors"] }, "EventLineupPersonLinkInput": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }, "EventLineupPersonMediaInput": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string", "nullable": true } }, "required": ["url"] }, "EventLineupPersonInput": { "type": "object", "properties": { "name": { "type": "string", "pattern": "\\S" }, "role": { "type": "string", "nullable": true, "description": "Shown under the person's name, e.g. their job title or act." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Avatar for this person. Must be a Cal Event media URL returned by the person avatar endpoint." }, "links": { "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/EventLineupPersonLinkInput" } }, "media": { "description": "Spotify, YouTube or SoundCloud links, shown as players with the person.", "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/EventLineupPersonMediaInput" } } }, "required": ["name"] }, "EventLineupInput": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "description": "Heading above the people on the event page." }, "people": { "maxItems": 30, "type": "array", "items": { "$ref": "#/components/schemas/EventLineupPersonInput" } } }, "required": ["people"] }, "EventSchedulePersonLinkInput": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }, "EventSchedulePersonInput": { "type": "object", "properties": { "name": { "type": "string", "pattern": "\\S" }, "role": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true, "description": "Avatar for this person. Must be a Cal Event media URL returned by the person avatar endpoint." }, "links": { "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/EventSchedulePersonLinkInput" } } }, "required": ["name"] }, "EventScheduleItemInput": { "type": "object", "properties": { "startTime": { "type": "string", "nullable": true, "description": "When the item starts, in ISO 8601 format in UTC timezone. Send either startTime or timeLabel. Required when endTime is set.", "example": "2030-01-01T10:10:00.000Z" }, "endTime": { "type": "string", "nullable": true, "description": "When the item ends, in ISO 8601 format in UTC timezone. Must be after startTime.", "example": "2030-01-01T10:40:00.000Z" }, "timeLabel": { "type": "string", "nullable": true, "pattern": "\\S", "description": "Free text such as \"Doors open\" for an item without a startTime. Send either startTime or timeLabel." }, "content": { "type": "string", "pattern": "\\S", "description": "What happens during this item." }, "people": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/EventSchedulePersonInput" } } }, "required": ["content"] }, "EventHostInput": { "type": "object", "properties": { "userId": { "type": "number", "minimum": 1, "example": 123 } }, "required": ["userId"] }, "EventLiveStreamInput": { "type": "object", "properties": { "url": { "type": "string", "description": "Where people can watch the event live.", "maxLength": 2048 } }, "required": ["url"] }, "CreateEventInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "The Event's title.", "example": "Team offsite", "maxLength": 255 }, "startTime": { "type": "string", "description": "When the Event starts, in ISO 8601 format in UTC timezone. It must not be in the past.", "example": "2030-01-01T10:00:00.000Z" }, "endTime": { "type": "string", "description": "When the Event ends, in ISO 8601 format in UTC timezone. It must be after `startTime`.", "example": "2030-01-01T11:00:00.000Z" }, "timeZone": { "type": "string", "description": "The IANA time zone the Event's times are shown in.", "example": "Europe/Berlin" }, "slug": { "type": "string", "description": "Public page slug (cal.com/{slug}): 10-100 lowercase letters, digits and hyphens. Generated from the title when omitted.", "example": "team-offsite-2030" }, "description": { "type": "string", "nullable": true, "description": "What the Event is about, shown on its page.", "maxLength": 5000 }, "visibility": { "enum": ["PUBLIC", "UNLISTED"], "type": "string", "description": "Once published: PUBLIC is listed on the owner's page, UNLISTED only opens from its link. Defaults to PUBLIC.", "default": "PUBLIC" }, "capacity": { "type": "number", "nullable": true, "minimum": 1, "description": "The most guests the Event can take. Omit or pass null for unlimited. Ignored once any location has its own `capacity`: the Event then takes the sum of the location capacities, or is unlimited if any location has none. The waitlist only opens when the Event or the chosen location is full, so it only works when capacity is set on the Event or on a location.", "maximum": 100000 }, "waitlistEnabled": { "type": "boolean", "description": "Let guests join a waitlist when the Event is full. The waitlist only opens when the Event or the chosen location is full, so it only works when capacity is set on the Event or on a location.", "default": false }, "paymentTimeoutMinutes": { "type": "number", "nullable": true, "minimum": 10, "maximum": 10080, "description": "How many minutes a guest's seat is held while they pay. null uses the default of 10 minutes." }, "registrationOpensAt": { "type": "string", "nullable": true, "description": "When guests can start registering, in ISO 8601 format in UTC timezone. Must be before registration closes. null opens registration when the Event is published.", "example": "2029-12-01T09:00:00.000Z" }, "registrationClosesAt": { "type": "string", "nullable": true, "description": "When registration closes, in ISO 8601 format in UTC timezone. Must not be after `startTime`. null closes registration when the Event starts. Guests already on the waitlist can still be promoted after it closes.", "example": "2029-12-31T12:00:00.000Z" }, "requiresApproval": { "type": "boolean", "description": "Registrations wait for a host's approval.", "default": false }, "showOrganizerEmail": { "type": "boolean", "description": "Show the organizer's email to guests.", "default": true }, "guestList": { "enum": ["hidden", "names", "count"], "type": "string", "description": "Who guests can see on the Event's page. `names` lists them, `count` shows how many, `hidden` shows neither. Defaults to `names`.", "default": "names" }, "showPresentedBy": { "type": "boolean", "description": "Show who the Event is presented by.", "default": true }, "theme": { "nullable": true, "enum": ["light", "dark"], "type": "string", "description": "Default theme of the event page. null follows the visitor's system setting." }, "background": { "nullable": true, "description": "Animated background of the event page.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventBackgroundInput" } ] }, "lineup": { "nullable": true, "description": "Speakers or performers on the event page. Avatars need the Event uuid, so create people without avatarUrl and upload avatars with the person avatar endpoint afterwards.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventLineupInput" } ] }, "schedule": { "description": "Agenda on the event page. Each item has either a startTime or a timeLabel. Avatars need the Event uuid, so create people without avatarUrl and upload avatars with the person avatar endpoint afterwards.", "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/EventScheduleItemInput" } }, "registrationFields": { "type": "array", "description": "The questions guests answer when they register.", "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] } }, "hosts": { "description": "The Event's hosts. The creator is always a host and always listed first, even when not passed. Personal Events can only have the creator, so passing other ids returns a 400. On team Events every id must be an accepted team member, otherwise it returns a 400.", "type": "array", "items": { "$ref": "#/components/schemas/EventHostInput" } }, "liveStreams": { "description": "Links where people can watch the event live.", "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/EventLiveStreamInput" } }, "category": { "enum": ["meetup", "conference", "music", "sports"], "type": "string", "description": "What kind of event it is. If not passed, it's guessed from the title." }, "price": { "type": "number", "nullable": true, "minimum": 1, "description": "Price of the Event, in the currency's smallest unit. Only for Events without locations, which need at least one live stream; Events with locations are priced per location. On update, null makes the Event free. Check `paymentsEnabled` on the Event before setting it.", "example": 1500 }, "currency": { "nullable": true, "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required when `price` is set.", "example": "usd" }, "locations": { "type": "array", "description": "Where the Event happens. Links can repeat. An Event can have one address and one conferencing location, either an integration or the organizer's default app.", "items": { "oneOf": [ { "$ref": "#/components/schemas/EventAddressLocationInput" }, { "$ref": "#/components/schemas/EventLinkLocationInput" }, { "$ref": "#/components/schemas/EventIntegrationLocationInput" }, { "$ref": "#/components/schemas/EventOrganizersDefaultAppLocationInput" } ] } } }, "required": ["title", "startTime", "endTime", "timeZone"] }, "EventOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventOutputDto" } }, "required": ["status", "data"] }, "UpdateEventInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "The Event's title.", "example": "Team offsite", "maxLength": 255 }, "endTime": { "type": "string", "description": "When the Event ends, in ISO 8601 format in UTC timezone. It must be after `startTime`.", "example": "2030-01-01T11:00:00.000Z" }, "timeZone": { "type": "string", "description": "The IANA time zone the Event's times are shown in.", "example": "Europe/Berlin" }, "description": { "type": "object", "nullable": true, "description": "What the Event is about, shown on its page.", "maxLength": 5000 }, "paymentTimeoutMinutes": { "type": "object", "nullable": true, "minimum": 10, "maximum": 10080, "description": "How many minutes a guest's seat is held while they pay. null uses the default of 10 minutes." }, "registrationOpensAt": { "type": "string", "nullable": true, "description": "When guests can start registering, in ISO 8601 format in UTC timezone. Must be before registration closes. null opens registration when the Event is published.", "example": "2029-12-01T09:00:00.000Z" }, "registrationClosesAt": { "type": "string", "nullable": true, "description": "When registration closes, in ISO 8601 format in UTC timezone. Must not be after `startTime`. null closes registration when the Event starts. Guests already on the waitlist can still be promoted after it closes.", "example": "2029-12-31T12:00:00.000Z" }, "theme": { "nullable": true, "enum": ["light", "dark"], "type": "string", "description": "Default theme of the event page. null follows the visitor's system setting." }, "background": { "nullable": true, "description": "Animated background of the event page.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventBackgroundInput" } ] }, "lineup": { "nullable": true, "description": "Speakers or performers on the event page. Avatars need the Event uuid, so create people without avatarUrl and upload avatars with the person avatar endpoint afterwards.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventLineupInput" } ] }, "schedule": { "description": "Agenda on the event page. Each item has either a startTime or a timeLabel. Avatars need the Event uuid, so create people without avatarUrl and upload avatars with the person avatar endpoint afterwards.", "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/EventScheduleItemInput" } }, "registrationFields": { "type": "array", "description": "The questions guests answer when they register.", "items": { "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldInput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldInput_2026_06_12" }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldInput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldInput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldInput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldInput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldInput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldInput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldInput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldInput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldInput_2026_06_12" }, { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldInput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldInput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldInput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldInput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldInput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldInput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldInput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldInput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldInput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldInput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldInput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldInput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldInput_2026_06_12" } ] } }, "hosts": { "description": "The Event's hosts. The creator is always a host and always listed first, even when not passed. Personal Events can only have the creator, so passing other ids returns a 400. On team Events every id must be an accepted team member, otherwise it returns a 400.", "type": "array", "items": { "$ref": "#/components/schemas/EventHostInput" } }, "liveStreams": { "description": "Links where people can watch the event live.", "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/EventLiveStreamInput" } }, "price": { "type": "number", "nullable": true, "minimum": 1, "description": "Price of the Event, in the currency's smallest unit. Only for Events without locations, which need at least one live stream; Events with locations are priced per location. On update, null makes the Event free. Check `paymentsEnabled` on the Event before setting it.", "example": 1500 }, "currency": { "nullable": true, "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required when `price` is set.", "example": "usd" }, "startTime": { "type": "string", "description": "When the Event starts, in ISO 8601 format in UTC timezone. It must be before `endTime`.", "example": "2030-01-01T10:00:00.000Z" }, "slug": { "type": "string", "description": "Public page slug (cal.com/{slug}): 10-100 lowercase letters, digits and hyphens. It can't change once the Event is published.", "example": "team-offsite-2030" }, "visibility": { "enum": ["PUBLIC", "UNLISTED"], "type": "string", "description": "Once published: PUBLIC is listed on the owner's page, UNLISTED only opens from its link." }, "capacity": { "type": "number", "nullable": true, "minimum": 1, "description": "The most guests the Event can take. Pass null for unlimited. Ignored once any location has its own `capacity`: the Event then takes the sum of the location capacities, or is unlimited if any location has none. It can't go below the number of confirmed guests.", "maximum": 100000 }, "waitlistEnabled": { "type": "boolean", "description": "Let guests join a waitlist when the Event is full. The waitlist only opens when the Event or the chosen location is full, so it only works when capacity is set on the Event or on a location." }, "requiresApproval": { "type": "boolean", "description": "Registrations wait for a host's approval." }, "showOrganizerEmail": { "type": "boolean", "description": "Show the organizer's email to guests." }, "guestList": { "enum": ["hidden", "names", "count"], "type": "string", "description": "Who guests can see on the Event's page. `names` lists them, `count` shows how many, `hidden` shows neither. It can't change once the Event is published." }, "showPresentedBy": { "type": "boolean", "description": "Show who the Event is presented by." }, "category": { "enum": ["meetup", "conference", "music", "sports"], "type": "string", "description": "What kind of event it is." } } }, "CancelEventInput": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Why the Event is cancelled. Included in the cancellation email every registered guest receives.", "example": "The venue fell through — we will announce a new date soon." } } }, "DeleteEventOutputDto": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the deleted Event." } }, "required": ["uuid"] }, "DeleteEventOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DeleteEventOutputDto" } }, "required": ["status", "data"] }, "EventBookingPaymentOutputDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the guest's payment went through." }, "refunded": { "type": "boolean", "description": "Whether the payment was refunded." }, "amount": { "type": "number", "example": 2000, "description": "Amount in the currency's smallest unit, for example cents." }, "currency": { "type": "string", "example": "eur", "description": "ISO 4217 currency code." } }, "required": ["success", "refunded", "amount", "currency"] }, "EventBookingOutputDto": { "type": "object", "properties": { "type": { "type": "string", "enum": ["event"], "description": "Discriminates this booking as a Cal Event attendee, as opposed to a regular booking." }, "registrationId": { "type": "string", "format": "uuid", "description": "The registration id. Pass this as `registrationId` to the check-in, approve and decline endpoints." }, "name": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string", "nullable": true }, "status": { "enum": [ "PENDING_APPROVAL", "WAITLISTED", "PENDING_PAYMENT", "PENDING_CONFIRMATION", "OFFER_EXPIRED", "CONFIRMED", "DECLINED", "CANCELLED" ], "type": "string" }, "rsvpResponse": { "enum": ["YES", "NO", "MAYBE"], "type": "string" }, "responses": { "type": "object", "nullable": true, "description": "Registration-form answers." }, "locationId": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "checkedInAt": { "format": "date-time", "type": "string", "nullable": true, "description": "When a door check-in was recorded." }, "checkedInByUserId": { "type": "number", "nullable": true, "description": "Host who recorded the door check-in." }, "avatarUrl": { "type": "string", "nullable": true, "description": "The guest's Cal.com profile photo when their email belongs to an account, otherwise an external avatar when one is found. `null` when neither exists." }, "payment": { "nullable": true, "description": "The guest's payment. `null` when the guest has no payment, for example on a free Event.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventBookingPaymentOutputDto" } ] }, "noShow": { "type": "boolean", "description": "Whether a host marked the guest as a no-show." }, "decidedAt": { "format": "date-time", "type": "string", "nullable": true, "description": "When a host approved or declined the guest. `null` until a host decides." } }, "required": [ "type", "registrationId", "name", "email", "status", "rsvpResponse", "createdAt", "noShow" ] }, "EventBookingsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventBookingOutputDto" } }, "pagination": { "$ref": "#/components/schemas/EventsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "RegistrationOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the registration." }, "name": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string", "nullable": true }, "status": { "enum": [ "PENDING_APPROVAL", "WAITLISTED", "PENDING_PAYMENT", "PENDING_CONFIRMATION", "OFFER_EXPIRED", "CONFIRMED", "DECLINED", "CANCELLED" ], "type": "string" }, "rsvpResponse": { "enum": ["YES", "NO", "MAYBE"], "type": "string" }, "responses": { "type": "object", "nullable": true, "description": "Registration-form answers." }, "locationId": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "checkedInAt": { "format": "date-time", "type": "string", "nullable": true, "description": "When a door check-in was recorded." }, "checkedInByUserId": { "type": "number", "nullable": true, "description": "Host who recorded the door check-in." } }, "required": ["id", "name", "email", "status", "rsvpResponse", "createdAt"] }, "CheckInOutcomeOutputDto": { "type": "object", "properties": { "kind": { "enum": ["checked_in", "already_checked_in", "not_confirmed"], "type": "string" }, "registration": { "$ref": "#/components/schemas/RegistrationOutputDto" }, "checkedInAt": { "format": "date-time", "type": "string", "description": "Set only when `kind` is `already_checked_in`." }, "status": { "enum": [ "PENDING_APPROVAL", "WAITLISTED", "PENDING_PAYMENT", "PENDING_CONFIRMATION", "OFFER_EXPIRED", "CONFIRMED", "DECLINED", "CANCELLED" ], "type": "string", "description": "Set only when `kind` is `not_confirmed`." } }, "required": ["kind"] }, "CheckInOutcomeOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CheckInOutcomeOutputDto" } }, "required": ["status", "data"] }, "UndoCheckInOutcomeOutputDto": { "type": "object", "properties": { "kind": { "enum": ["undone", "not_checked_in"], "type": "string" }, "registration": { "$ref": "#/components/schemas/RegistrationOutputDto" } }, "required": ["kind"] }, "UndoCheckInOutcomeOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UndoCheckInOutcomeOutputDto" } }, "required": ["status", "data"] }, "CheckInByTokenInput": { "type": "object", "properties": { "checkInToken": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The signed check-in token scanned from the guest's QR code." } }, "required": ["checkInToken"] }, "ApproveAllRegistrationsInput": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 255, "description": "Only approve guests whose name or email contains this text, case-insensitive." }, "locationId": { "type": "string", "maxLength": 128, "description": "Only approve guests who registered for this location." }, "retry": { "type": "boolean", "description": "Paid Events only: when the previous approve-all failed, approve the guests it had not reached instead of reading the pending guests again." } } }, "ApproveAllOutcomeOutputDto": { "type": "object", "properties": { "kind": { "enum": ["completed", "started"], "type": "string", "description": "`completed` when every pending guest was handled in this request. `started` when a paid Event's approval runs in the background." }, "approvedCount": { "type": "number", "description": "Set only when `kind` is `completed`. Guests approved; on a paid Event, guests sent a payment request." }, "notSeatedCount": { "type": "number", "description": "Set only when `kind` is `completed`. Guests left pending because the Event is full." }, "operationId": { "type": "string", "description": "Set only when `kind` is `started`. Identifies the background approval." }, "total": { "type": "number", "description": "Set only when `kind` is `started`. Guests the background approval will handle." } }, "required": ["kind"] }, "ApproveAllOutcomeOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ApproveAllOutcomeOutputDto" } }, "required": ["status", "data"] }, "RegistrationDecisionOutcomeOutputDto": { "type": "object", "properties": { "kind": { "enum": ["confirmed", "payment_pending", "declined", "waitlisted", "event_full_offer_waitlist"], "type": "string", "description": "`confirmed` when the guest got a seat. `payment_pending` when a paid Event sent the guest a payment request; the guest is confirmed once they pay. `event_full_offer_waitlist` when the Event is full; the guest stays pending. `declined` when the guest was declined." }, "registration": { "$ref": "#/components/schemas/RegistrationOutputDto" } }, "required": ["kind", "registration"] }, "RegistrationDecisionOutcomeOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/RegistrationDecisionOutcomeOutputDto" } }, "required": ["status", "data"] }, "RegistrationRsvpCountsOutputDto": { "type": "object", "properties": { "yes": { "type": "number", "description": "Guests who answered Yes, in any status." }, "no": { "type": "number", "description": "Guests who answered No, in any status." }, "maybe": { "type": "number", "description": "Guests who answered Maybe, in any status." } }, "required": ["yes", "no", "maybe"] }, "RegistrationLocationCountOutputDto": { "type": "object", "properties": { "locationId": { "type": "string", "nullable": true, "description": "Event location id, or null for guests not registered for a location." }, "count": { "type": "number", "description": "Seats held at this location by confirmed guests and guests holding a seat while they pay or confirm." } }, "required": ["locationId", "count"] }, "RegistrationCountsOutputDto": { "type": "object", "properties": { "pendingApproval": { "type": "number", "description": "Guests waiting for approval." }, "waitlisted": { "type": "number", "description": "Guests on the waitlist." }, "pendingPayment": { "type": "number", "description": "Guests sent a payment request who have not paid yet." }, "offerExpired": { "type": "number", "description": "Guests whose payment request expired." }, "declined": { "type": "number", "description": "Declined guests." }, "cancelled": { "type": "number", "description": "Guests who cancelled." }, "confirmed": { "type": "number", "description": "Confirmed guests, whatever their RSVP." }, "going": { "type": "number", "description": "Confirmed guests who answered Yes." }, "checkedIn": { "type": "number", "description": "Confirmed guests with a recorded door check-in." }, "rsvpResponses": { "$ref": "#/components/schemas/RegistrationRsvpCountsOutputDto" }, "byLocation": { "description": "Seats held per location.", "type": "array", "items": { "$ref": "#/components/schemas/RegistrationLocationCountOutputDto" } } }, "required": [ "pendingApproval", "waitlisted", "pendingPayment", "offerExpired", "declined", "cancelled", "confirmed", "going", "checkedIn", "rsvpResponses", "byLocation" ] }, "RegistrationCountsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/RegistrationCountsOutputDto" } }, "required": ["status", "data"] }, "CoHostOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the co-host on this Event. Not a user id.", "format": "uuid" }, "email": { "type": "string", "description": "The invited email address, lowercased." }, "status": { "enum": ["PENDING", "ACCEPTED", "DECLINED"], "type": "string" }, "name": { "type": "string", "nullable": true, "description": "Display name, set once the invite is accepted." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Avatar URL, set once the invite is accepted." } }, "required": ["id", "email", "status"] }, "CoHostsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CoHostOutputDto" } } }, "required": ["status", "data"] }, "InviteCoHostInput": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320, "description": "Email address to invite as a co-host. Trimmed and lowercased; it must be deliverable and not on a blocklist.", "example": "co-host@example.com" } }, "required": ["email"] }, "InvitedCoHostOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the co-host on this Event. Not a user id.", "format": "uuid" }, "email": { "type": "string", "description": "The invited email address, lowercased." }, "status": { "enum": ["PENDING", "ACCEPTED", "DECLINED"], "type": "string" } }, "required": ["id", "email", "status"] }, "InviteCoHostOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/InvitedCoHostOutputDto" } }, "required": ["status", "data"] }, "ReorderCoHostsInput": { "type": "object", "properties": { "coHostIds": { "maxItems": 500, "description": "Every co-host id on the Event, accepted and pending alike, in the new display order. Each id must appear exactly once. These are the `id` values from `GET /v2/events/{uuid}/co-hosts`, not user ids.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": ["coHostIds"] }, "CoHostsActionOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "HostCandidateOutputDto": { "type": "object", "properties": { "userId": { "type": "number", "description": "User id. Send it in `hosts` when updating the Event.", "example": 42 }, "name": { "type": "string", "nullable": true, "example": "Ada Lovelace" }, "username": { "type": "string", "nullable": true, "example": "ada" }, "email": { "type": "string", "example": "ada@example.com" }, "avatarUrl": { "type": "string", "nullable": true } }, "required": ["userId", "name", "username", "email", "avatarUrl"] }, "HostCandidatesOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HostCandidateOutputDto" } }, "pagination": { "$ref": "#/components/schemas/EventsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "EventCoordinatesOutput": { "type": "object", "properties": { "latitude": { "type": "number", "example": 51.5092, "description": "Latitude shown on the public Event page's map." }, "longitude": { "type": "number", "example": -0.1278, "description": "Longitude shown on the public Event page's map." } }, "required": ["latitude", "longitude"] }, "EventCoordinatesOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventCoordinatesOutput" } }, "required": ["status", "data"] }, "UpdateEventCoordinatesInput": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude of the Event's address location. Must stay within 1 km of the geocoded address.", "example": 51.5092 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude of the Event's address location. Must stay within 1 km of the geocoded address.", "example": -0.1278 } }, "required": ["latitude", "longitude"] }, "UpdateEventCoordinatesOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" } }, "required": ["status"] }, "EventCoverImageOutputDto": { "type": "object", "properties": { "coverImageUrl": { "type": "string", "description": "Public URL of the uploaded cover image." }, "coverImageWidth": { "type": "number", "description": "Width of the cover image in pixels, as displayed." }, "coverImageHeight": { "type": "number", "description": "Height of the cover image in pixels, as displayed." } }, "required": ["coverImageUrl", "coverImageWidth", "coverImageHeight"] }, "EventCoverImageOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventCoverImageOutputDto" } }, "required": ["status", "data"] }, "DeleteEventCoverImageOutputDto": { "type": "object", "properties": { "coverImageUrl": { "type": "string", "nullable": true, "example": null, "description": "Always `null` once removed." } }, "required": ["coverImageUrl"] }, "DeleteEventCoverImageOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DeleteEventCoverImageOutputDto" } }, "required": ["status", "data"] }, "UpdateEventAddressLocationInput": { "type": "object", "properties": { "label": { "type": "string", "nullable": true, "description": "Name shown for this location. Pass null to remove it.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "minimum": 1, "description": "Price for this location, in the currency's smallest unit. Pass null to make it free.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required with `price` when the location has no currency yet.", "example": "usd" }, "capacity": { "type": "number", "nullable": true, "minimum": 1, "description": "Seats at this location. Pass null for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "address", "enum": ["address"], "description": "The location's type. It can't change." }, "address": { "type": "string", "minLength": 1, "example": "1 Example Street, Berlin" } }, "required": ["type"] }, "UpdateEventLinkLocationInput": { "type": "object", "properties": { "label": { "type": "string", "nullable": true, "description": "Name shown for this location. Pass null to remove it.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "minimum": 1, "description": "Price for this location, in the currency's smallest unit. Pass null to make it free.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required with `price` when the location has no currency yet.", "example": "usd" }, "capacity": { "type": "number", "nullable": true, "minimum": 1, "description": "Seats at this location. Pass null for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "link", "enum": ["link"], "description": "The location's type. It can't change." }, "link": { "type": "string", "format": "uri", "example": "https://example.com/watch" } }, "required": ["type"] }, "UpdateEventIntegrationLocationInput": { "type": "object", "properties": { "label": { "type": "string", "nullable": true, "description": "Name shown for this location. Pass null to remove it.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "minimum": 1, "description": "Price for this location, in the currency's smallest unit. Pass null to make it free.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required with `price` when the location has no currency yet.", "example": "usd" }, "capacity": { "type": "number", "nullable": true, "minimum": 1, "description": "Seats at this location. Pass null for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "integration", "enum": ["integration"], "description": "The location's type. It can't change." }, "integration": { "enum": [ "cal-video", "google-meet", "zoom", "whereby-video", "whatsapp-video", "webex-video", "telegram-video", "tandem", "sylaps-video", "skype-video", "sirius-video", "signal-video", "shimmer-video", "salesroom-video", "roam-video", "riverside-video", "ping-video", "office365-video", "mirotalk-video", "jitsi", "jelly-video", "jelly-conferencing", "huddle", "facetime-video", "element-call-video", "eightxeight-video", "discord-video", "demodesk-video", "campfire-video" ], "type": "string", "example": "cal-video", "description": "Switching the integration drops the stored `credentialId` unless a new one is sent." }, "credentialId": { "type": "number", "description": "Identifies which connected account will host the Event when a host has multiple connected accounts." } }, "required": ["type"] }, "UpdateEventOrganizersDefaultAppLocationInput": { "type": "object", "properties": { "label": { "type": "string", "nullable": true, "description": "Name shown for this location. Pass null to remove it.", "maxLength": 100 }, "price": { "type": "number", "nullable": true, "minimum": 1, "description": "Price for this location, in the currency's smallest unit. Pass null to make it free.", "example": 1500 }, "currency": { "enum": [ "usd", "eur", "gbp", "cad", "aud", "chf", "nzd", "jpy", "brl", "mxn", "inr", "sgd", "hkd", "dkk", "nok", "sek", "pln", "czk", "huf", "ron", "bgn", "krw", "thb", "php", "myr", "idr", "try", "zar", "aed", "cop" ], "type": "string", "description": "Cal Pay currency code. Required with `price` when the location has no currency yet.", "example": "usd" }, "capacity": { "type": "number", "nullable": true, "minimum": 1, "description": "Seats at this location. Pass null for unlimited. All locations together can have at most 100000 seats.", "maximum": 100000 }, "type": { "type": "string", "example": "organizersDefaultApp", "enum": ["organizersDefaultApp"], "description": "The location's type. It can't change." } }, "required": ["type"] }, "EventLocationsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/EventAddressLocationOutput" }, { "title": "Link", "$ref": "#/components/schemas/EventLinkLocationOutput" }, { "title": "Integration", "$ref": "#/components/schemas/EventIntegrationLocationOutput" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/EventOrganizersDefaultAppLocationOutput" }, { "title": "Unknown", "$ref": "#/components/schemas/EventUnknownLocationOutput" } ] } } }, "required": ["status", "data"] }, "EventLocationOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "oneOf": [ { "title": "Address", "$ref": "#/components/schemas/EventAddressLocationOutput" }, { "title": "Link", "$ref": "#/components/schemas/EventLinkLocationOutput" }, { "title": "Integration", "$ref": "#/components/schemas/EventIntegrationLocationOutput" }, { "title": "Organizer Default App", "$ref": "#/components/schemas/EventOrganizersDefaultAppLocationOutput" } ] } }, "required": ["status", "data"] }, "EventPersonAvatarOutputDto": { "type": "object", "properties": { "avatarUrl": { "type": "string", "description": "Public URL of the uploaded image. Set it as a lineup or schedule person's `avatarUrl` when updating the Event." } }, "required": ["avatarUrl"] }, "EventPersonAvatarOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/EventPersonAvatarOutputDto" } }, "required": ["status", "data"] }, "SendMessageInput": { "type": "object", "properties": { "segment": { "enum": ["GOING", "MAYBE", "PENDING"], "type": "string", "description": "Which guests receive the message: `GOING` (confirmed, RSVP yes), `MAYBE` (confirmed, RSVP maybe) or `PENDING` (waiting for approval)." }, "subject": { "type": "string", "description": "Email subject in plain text, up to 200 characters. HTML is refused." }, "body": { "type": "string", "description": "Message in plain text, up to 5000 characters. Links are allowed as plain URLs; HTML is refused." }, "scheduledAt": { "type": "string", "description": "When to send the message, as an ISO 8601 date-time such as `2030-01-01T09:00:00Z`. It must be at least 5 minutes from now and earlier than 7 days after the Event ends. Omit it to send the message now. Cancel a scheduled message before this time with the cancel endpoint.", "example": "2030-01-01T09:00:00Z" }, "locationId": { "type": "string", "maxLength": 128, "description": "Only message guests who registered for this location of the Event." }, "checkedIn": { "type": "boolean", "description": "Only message guests who checked in (`true`) or who did not (`false`). Omit to message both." } }, "required": ["segment", "subject", "body"] }, "SendMessageOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the message." }, "status": { "enum": ["QUEUED", "FAILED_TO_QUEUE"], "type": "string", "description": "`QUEUED` when the message is on its way, or waiting for its `scheduledAt`; `FAILED_TO_QUEUE` when it could not be queued and nothing was sent." }, "scheduledAt": { "format": "date-time", "type": "string", "description": "When the message will be sent. Present only for a scheduled message." }, "recipientCount": { "type": "number", "description": "How many guests will be emailed." }, "textRecipientCount": { "type": "number", "description": "How many guests will be texted instead, because they have only a phone number." }, "skippedPhoneCount": { "type": "number", "description": "Guests in the segment who have only a phone number and will not be texted." } }, "required": ["id", "status", "recipientCount", "textRecipientCount", "skippedPhoneCount"] }, "SendMessageOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SendMessageOutputDto" } }, "required": ["status", "data"] }, "CancelMessageOutputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the message." }, "status": { "type": "string", "enum": ["CANCELLED"], "description": "The message was cancelled and will not be sent." } }, "required": ["id", "status"] }, "CancelMessageOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CancelMessageOutputDto" } }, "required": ["status", "data"] }, "MessageSenderOutputDto": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string", "nullable": true } }, "required": ["id"] }, "MessageCountsOutputDto": { "type": "object", "properties": { "sentCount": { "type": "number", "description": "Emails sent." }, "failedCount": { "type": "number", "description": "Emails that failed to send." }, "textedCount": { "type": "number", "description": "Texts sent to guests who have only a phone number." }, "textFailedCount": { "type": "number", "description": "Texts that failed to send." }, "skippedPhoneCount": { "type": "number", "description": "Guests skipped because they have only a phone number and were not texted." }, "skippedUnsubscribedCount": { "type": "number", "description": "Guests skipped because they unsubscribed from the Event's emails." } }, "required": [ "sentCount", "failedCount", "textedCount", "textFailedCount", "skippedPhoneCount", "skippedUnsubscribedCount" ] }, "MessageOutputDto": { "type": "object", "properties": { "id": { "type": "string" }, "segment": { "enum": ["GOING", "MAYBE", "PENDING"], "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "sender": { "nullable": true, "description": "`null` once the sender's account is deleted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MessageSenderOutputDto" } ] }, "status": { "enum": [ "SCHEDULED", "SENDING", "SENT", "PARTIALLY_SENT", "NOT_SENT", "NOT_SENT_EVENT_UNSENDABLE", "CANCELLED" ], "type": "string", "description": "`SCHEDULED` while it waits for its time, `SENDING` while it goes out, `SENT`, `PARTIALLY_SENT`, `NOT_SENT`, `NOT_SENT_EVENT_UNSENDABLE` when the Event stopped accepting messages before it went out, or `CANCELLED` when it was cancelled before its time." }, "scheduledAt": { "format": "date-time", "type": "string", "description": "When a scheduled message goes out, or was meant to. Absent for a message sent at once." }, "counts": { "nullable": true, "description": "`null` while sending and whenever nothing was delivered.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MessageCountsOutputDto" } ] } }, "required": ["id", "segment", "createdAt", "status"] }, "MessagesOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageOutputDto" } }, "pagination": { "$ref": "#/components/schemas/EventsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "InviteGuestsInput": { "type": "object", "properties": { "emails": { "description": "Email addresses to invite, up to 200 per request. Send at least one email, `contactIds` or `contactTagIds`.", "example": ["guest@example.com"], "type": "array", "items": { "type": "string", "format": "email" } }, "contactIds": { "minItems": 1, "description": "Ids of the authenticated user's own contacts, from `GET /v2/contacts`. Each contact is invited at its email, and they count with `emails` and `contactTagIds` toward the 200 guests one request can invite. Requires the `contacts` feature. A contact the user doesn't own is a 400.", "example": ["0192f3a1-7c2b-7d4e-9a10-0000000000a1"], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid" } }, "contactTagIds": { "minItems": 1, "description": "Ids of the authenticated user's own contact tags, from the `tags` of each contact in `GET /v2/contacts`. Every contact with one of these tags is invited, and they count with `emails` and `contactIds` toward the 200 guests one request can invite. Requires the `contacts` feature. A tag the user doesn't own is a 400.", "example": ["0192f3a1-7c2b-7d4e-9a10-00000000000a"], "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid" } }, "hostNote": { "type": "string", "maxLength": 500, "description": "A personal note from the host, included in the invitation email." } } }, "InviteOutcomeOutputDto": { "type": "object", "properties": { "email": { "type": "string" }, "reason": { "enum": [ "invited", "already-invited", "already-registered", "cooldown", "invalid-format", "undeliverable", "duplicate", "failed" ], "type": "string", "description": "What happened to this address: `invited`; skipped as `already-invited`, `already-registered` or `cooldown` (re-invited too recently); rejected as `invalid-format`, `undeliverable` or `duplicate` (repeated in this request); or `failed`, which can be retried." } }, "required": ["email", "reason"] }, "InviteGuestsOutputDto": { "type": "object", "properties": { "invitedCount": { "type": "number" }, "skippedAlreadyInvited": { "type": "number" }, "skippedAlreadyRegistered": { "type": "number" }, "skippedOnCooldown": { "type": "number" }, "skippedInvalid": { "type": "number" }, "failedCount": { "type": "number", "description": "Addresses whose invitation could not be saved. They can be retried." }, "outcomes": { "description": "One entry per submitted address.", "type": "array", "items": { "$ref": "#/components/schemas/InviteOutcomeOutputDto" } } }, "required": [ "invitedCount", "skippedAlreadyInvited", "skippedAlreadyRegistered", "skippedOnCooldown", "skippedInvalid", "failedCount", "outcomes" ] }, "InviteGuestsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/InviteGuestsOutputDto" } }, "required": ["status", "data"] }, "ContactTagOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-00000000000a" }, "name": { "type": "string", "example": "Investors" } }, "required": ["id", "name"] }, "CalUserContactOutput": { "type": "object", "properties": { "type": { "enum": ["calUser"], "type": "string", "description": "The email belongs to a verified, discoverable Cal account. The contact shows the name from that account, and its name can't be changed.", "example": "calUser" }, "id": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-000000000001" }, "name": { "type": "string", "nullable": true, "description": "The name from the contact's Cal account, or the stored name when that account has none.", "example": "Jamie Rivera" }, "email": { "type": "string", "example": "jamie.rivera@example.com" }, "tags": { "description": "The user's own tags on this contact.", "type": "array", "items": { "$ref": "#/components/schemas/ContactTagOutput" } }, "username": { "type": "string", "nullable": true, "description": "The Cal account's username, null when the account has none yet.", "example": "jamie" }, "bookingUrl": { "type": "string", "nullable": true, "description": "Full URL to the contact's booking page, null when the account has no username yet.", "example": "https://cal.com/jamie" }, "groupBooking": { "enum": ["eligible", "outsideOrganization", "unavailable"], "type": "string", "description": "Whether this contact can join a dynamic group booking with the authenticated user. eligible: available for group booking with them; outsideOrganization: in a different organization; unavailable: dynamic group booking is unavailable (disabled, locked or the user themself)." } }, "required": ["type", "id", "name", "email", "tags", "username", "bookingUrl", "groupBooking"] }, "NonCalUserContactOutput": { "type": "object", "properties": { "type": { "enum": ["nonCalUser"], "type": "string", "description": "The email doesn't belong to a verified, discoverable Cal account.", "example": "nonCalUser" }, "id": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-000000000001" }, "name": { "type": "string", "nullable": true, "description": "The name the user stored for this contact.", "example": "Jamie Rivera" }, "email": { "type": "string", "example": "jamie.rivera@example.com" }, "tags": { "description": "The user's own tags on this contact.", "type": "array", "items": { "$ref": "#/components/schemas/ContactTagOutput" } } }, "required": ["type", "id", "name", "email", "tags"] }, "ContactsCursorPaginationMetaDto": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor to fetch the next page. Pass this value as the cursor query parameter with the same filters. null when hasMore is false." }, "hasMore": { "type": "boolean", "description": "Whether more pages are available after this one." } }, "required": ["nextCursor", "hasMore"] }, "ListContactsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Contact on Cal", "$ref": "#/components/schemas/CalUserContactOutput" }, { "title": "Contact not on Cal", "$ref": "#/components/schemas/NonCalUserContactOutput" } ], "discriminator": { "propertyName": "type", "mapping": { "calUser": "#/components/schemas/CalUserContactOutput", "nonCalUser": "#/components/schemas/NonCalUserContactOutput" } } }, "description": "The contacts on this page, discriminated by `type`. Only a contact on Cal has a username, booking URL and group booking eligibility." }, "pagination": { "$ref": "#/components/schemas/ContactsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "ContactTagWithCountOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-00000000000a" }, "name": { "type": "string", "example": "Investors" }, "contactCount": { "type": "number", "description": "How many of the user's contacts carry this tag.", "example": 3 } }, "required": ["id", "name", "contactCount"] }, "ListContactTagsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactTagWithCountOutput" } }, "pagination": { "$ref": "#/components/schemas/ContactsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "CreateContactTagInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The tag's name.", "example": "Investors", "maxLength": 50 }, "color": { "type": "string", "description": "A hex color. Leave out for the default.", "example": "#0ea5e9", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" } }, "required": ["name"] }, "CreateContactTagOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ContactTagOutput" } }, "required": ["status", "data"] }, "CreateContactInput": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "The email address to add. It is checked for its format and mail server, and stored lowercased.", "example": "jamie.rivera@example.com", "maxLength": 254 }, "name": { "type": "string", "description": "The contact's name. Leave out when there is none.", "example": "Jamie Rivera", "maxLength": 50 } }, "required": ["email"] }, "CreatedContactOutput": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address that was added.", "example": "jamie.rivera@example.com" } }, "required": ["email"] }, "CreateContactOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CreatedContactOutput" } }, "required": ["status", "data"] }, "UpdateContactInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The contact's new name. A contact on Cal (`type: calUser`) can't have its name changed.", "example": "Jamie R.", "maxLength": 50 } } }, "UpdatedContactOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-000000000001" }, "name": { "type": "string", "nullable": true, "description": "The contact's name after the update, as the list shows it.", "example": "Jamie R." } }, "required": ["id", "name"] }, "UpdateContactOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UpdatedContactOutput" } }, "required": ["status", "data"] }, "AddContactTagInput": { "type": "object", "properties": { "tagId": { "type": "string", "format": "uuid", "description": "The id of one of the user's own tags, from `GET /v2/contacts/tags`.", "example": "0192f3a1-7c2b-7d4e-9a10-00000000000a" } }, "required": ["tagId"] }, "ContactTagChangeOutput": { "type": "object", "properties": { "contactId": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-000000000001" }, "tagId": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-00000000000a" } }, "required": ["contactId", "tagId"] }, "ContactTagChangeOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ContactTagChangeOutput" } }, "required": ["status", "data"] }, "RemovedContactOutput": { "type": "object", "properties": { "id": { "type": "string", "example": "0192f3a1-7c2b-7d4e-9a10-000000000001" } }, "required": ["id"] }, "RemoveContactOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/RemovedContactOutput" } }, "required": ["status", "data"] }, "ContactSuggestionOutput": { "type": "object", "properties": { "email": { "type": "string", "description": "The attendee's email, lowercased.", "example": "jamie.rivera@example.com" }, "name": { "type": "string", "description": "The attendee's name on the most recent booking with them.", "example": "Jamie Rivera" }, "meetingCount": { "type": "number", "description": "How many accepted, past bookings the user hosted with this attendee in the last 12 months.", "example": 6 }, "lastMetAt": { "type": "string", "description": "When the most recent of those bookings was made, in ISO 8601 UTC.", "example": "2026-10-02T09:30:00.000Z" } }, "required": ["email", "name", "meetingCount", "lastMetAt"] }, "ListContactSuggestionsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactSuggestionOutput" } }, "pagination": { "$ref": "#/components/schemas/ContactsCursorPaginationMetaDto" } }, "required": ["status", "data", "pagination"] }, "DismissContactSuggestionInput": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "The suggestion's email from `GET /v2/contacts/suggestions`. It is matched without regard to case or surrounding spaces.", "example": "jamie.rivera@example.com", "maxLength": 254 } }, "required": ["email"] }, "DismissedContactSuggestionOutput": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address that was dismissed.", "example": "jamie.rivera@example.com" } }, "required": ["email"] }, "DismissContactSuggestionOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/DismissedContactSuggestionOutput" } }, "required": ["status", "data"] }, "DiscoverListingOutput": { "type": "object", "properties": { "listingId": { "type": "number", "example": 12, "description": "The Discover listing id." }, "service": { "type": "string", "example": "Deep tissue massage", "description": "The service's name, as its card shows it." }, "provider": { "type": "string", "nullable": true, "example": "Riverside Massage", "description": "The provider's name; null when the listing shows none." }, "priceInCents": { "type": "number", "nullable": true, "example": 9000, "description": "The price in the currency's minor unit; null when no price is listed, which is not free." }, "currency": { "type": "string", "example": "usd", "description": "The price's ISO 4217 currency code." }, "price": { "type": "string", "example": "$90.00", "description": "The price as the card shows it: a formatted amount, `free`, or `not listed`." }, "newClientDiscountPercent": { "type": "number", "nullable": true, "example": 15, "description": "The discount, in percent, a new client gets when booking through Discover; null when none." }, "rating": { "type": "number", "nullable": true, "example": 4.8, "description": "The provider's aggregate rating out of 5; null when unrated." }, "reviewCount": { "type": "number", "nullable": true, "example": 132, "description": "How many reviews the rating is based on; null when unrated." }, "verified": { "type": "boolean", "example": true, "description": "Whether the provider is verified." }, "durationMinutes": { "type": "number", "example": 60, "description": "The service's length in minutes." }, "online": { "type": "boolean", "example": false, "description": "Whether the service is online rather than at a place." }, "city": { "type": "string", "nullable": true, "example": "Austin", "description": "The city the card shows; null for an online listing or one whose city is not shown." }, "neighborhood": { "type": "string", "nullable": true, "example": "Zilker", "description": "The neighborhood the card shows; null when none, or when city is null." }, "timeZone": { "type": "string", "nullable": true, "example": "America/Chicago", "description": "The business's IANA time zone; null when unknown." }, "nextAvailableChecked": { "type": "boolean", "example": true, "description": "Only with `includeNextAvailable`: whether the earliest open slot was looked up. False past the first 10 listings." }, "nextAvailableSlot": { "type": "string", "nullable": true, "example": "2026-11-10T15:00:00.000Z", "description": "Only with `includeNextAvailable`: the ISO 8601 start of the earliest open slot in the next 7 days; null when none or not checked." } }, "required": [ "listingId", "service", "provider", "priceInCents", "currency", "price", "newClientDiscountPercent", "rating", "reviewCount", "verified", "durationMinutes", "online", "city", "neighborhood", "timeZone" ] }, "GetDiscoverListingsData": { "type": "object", "properties": { "listings": { "description": "The published listings among the requested ids, in the order asked. Review text, addresses, coordinates, descriptions, bios, photos and contact details are never returned.", "type": "array", "items": { "$ref": "#/components/schemas/DiscoverListingOutput" } }, "notFoundListingIds": { "example": [56], "description": "Requested ids that are not a published listing: unknown, unpublished or hidden.", "type": "array", "items": { "type": "number" } } }, "required": ["listings", "notFoundListingIds"] }, "GetDiscoverListingsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/GetDiscoverListingsData" } }, "required": ["status", "data"] }, "DiscoverListingSearchResultOutput": { "type": "object", "properties": { "listingId": { "type": "number", "example": 12, "description": "The Discover listing id, which `GET /v2/discover/listings` reads." }, "title": { "type": "string", "example": "Skin fade", "description": "The service's name." }, "description": { "type": "string", "nullable": true, "example": "A sharp fade with a hot-towel finish.", "description": "The listing's description; null when it has none." }, "provider": { "type": "string", "nullable": true, "example": "Fade House", "description": "The provider's name; null when the listing shows none." }, "avatarUrl": { "type": "string", "nullable": true, "example": "https://cal.com/api/avatar/fade-house.png", "description": "The provider's avatar or team logo URL; null when none." }, "category": { "type": "string", "enum": [ "MEDICAL", "BARBERS", "COACHING", "CONSULTING", "LESSONS", "PETS", "SPORTS", "DANCE", "SOCIAL", "ONLINE_SERVICES", "SAAS", "HOME_SERVICES", "OTHER" ], "example": "BARBERS", "description": "The listing's category." }, "subcategory": { "type": "string", "nullable": true, "example": "haircuts", "description": "The listing's subcategory slug; null when none." }, "city": { "type": "string", "nullable": true, "example": "Seattle", "description": "The city the listing's card shows; null for an online listing." }, "neighborhood": { "type": "string", "nullable": true, "example": "Capitol Hill", "description": "The listing's neighborhood; null for an online listing or when none is known." }, "timeZone": { "type": "string", "nullable": true, "example": "America/Los_Angeles", "description": "The business's IANA time zone, which an in-person slot is shown in; null for an online listing." }, "latitude": { "type": "number", "nullable": true, "example": 47.62, "description": "The listing's public, rounded latitude; null when the business is not geocoded." }, "longitude": { "type": "number", "nullable": true, "example": -122.32, "description": "The listing's public, rounded longitude; null when the business is not geocoded." }, "distanceMiles": { "type": "number", "nullable": true, "example": 1.4, "description": "Miles from the searched area's centre to the listing, to one decimal; null without an area or a location." }, "durationMinutes": { "type": "number", "example": 30, "description": "The session's length in minutes." }, "priceInCents": { "type": "number", "nullable": true, "example": 4500, "description": "The price in the currency's minor unit; null when no price is listed, which is not free." }, "currency": { "type": "string", "example": "usd", "description": "The price's ISO 4217 currency code." }, "price": { "type": "string", "example": "45.00 USD", "description": "The price in words: an amount with its currency, `free`, or `not listed`." }, "rating": { "type": "number", "nullable": true, "example": 4.8, "description": "The provider's aggregate rating out of 5; null when unrated." }, "reviewCount": { "type": "number", "nullable": true, "example": 132, "description": "How many reviews the rating is based on; null when unrated." }, "openNow": { "type": "boolean", "example": true, "description": "Whether the business is open now." }, "verified": { "type": "boolean", "example": true, "description": "Whether the provider is verified." }, "newClientDiscountPercent": { "type": "number", "nullable": true, "example": 15, "description": "The discount, in percent, a new client gets on a first visit booked through Discover; null when none." }, "path": { "type": "string", "nullable": true, "example": "/discover/fade-house/skin-fade", "description": "The listing's Discover page path on the web app; null when the provider has no Discover page." }, "bookingUrl": { "type": "string", "nullable": true, "example": "https://cal.com/fade-house/skin-fade?utm_source=discover&utm_medium=api&utm_campaign=barbers&utm_content=listing%3A12", "description": "The listing's booking page, attributed to Discover so its new-client discount applies; null when the listing has no booking page." }, "nextAvailableSlot": { "type": "string", "nullable": true, "example": "2026-11-10T17:00:00.000Z", "description": "The ISO 8601 start of the earliest open slot in the searched window; null when none was found." }, "nextAvailableSlotLocal": { "type": "string", "nullable": true, "example": "Today, 9:00 AM PST", "description": "That slot as the listing's card shows it, in `timeZone`, else your saved time zone; null when none." }, "nextAvailableSlotTimeZone": { "type": "string", "nullable": true, "example": "PST", "description": "The time zone abbreviation `nextAvailableSlotLocal` is in; null when none." } }, "required": [ "listingId", "title", "description", "provider", "avatarUrl", "category", "subcategory", "city", "neighborhood", "timeZone", "latitude", "longitude", "distanceMiles", "durationMinutes", "priceInCents", "currency", "price", "rating", "reviewCount", "openNow", "verified", "newClientDiscountPercent", "path", "bookingUrl", "nextAvailableSlot", "nextAvailableSlotLocal", "nextAvailableSlotTimeZone" ] }, "DiscoverSearchBroadenedFromOutput": { "type": "object", "properties": { "subcategory": { "type": "string", "example": "haircuts", "description": "The subcategory the search dropped." }, "query": { "type": "string", "example": "skin fade", "description": "The free text the search dropped." } } }, "DiscoverWebBusinessOutput": { "type": "object", "properties": { "name": { "type": "string", "example": "Example Barbers", "description": "The business's name, from its website." }, "url": { "type": "string", "example": "https://barbers.example/book", "description": "The page the business was found on." }, "description": { "type": "string", "nullable": true, "example": "Fades and beard trims", "description": "What the page says the business offers; null when it says nothing usable." }, "appointmentEmails": { "example": ["bookings@barbers.example"], "description": "Email addresses the business's page offers for making an appointment.", "type": "array", "items": { "type": "string" } }, "appointmentPhones": { "example": ["(415) 555-0101"], "description": "Phone numbers the business's page offers for making an appointment.", "type": "array", "items": { "type": "string" } } }, "required": ["name", "url", "description", "appointmentEmails", "appointmentPhones"] }, "SearchDiscoverListingsData": { "type": "object", "properties": { "areaNeeded": { "type": "boolean", "example": true, "description": "Present, and true, only when nothing was searched. Without `areaNotFound`, no `area` was given and there is no saved ZIP code: search again with `area` set. With `areaNotFound`, see that field. No search fields are present then." }, "areaNotFound": { "type": "boolean", "example": true, "description": "Present, and true, only with `areaNeeded`: the named `area`, or your saved ZIP code when no `area` was given, could not be found. Search again with a nearby city or a ZIP code, not the same place." }, "totalMatches": { "type": "number", "example": 3, "description": "How many published listings matched." }, "results": { "description": "Up to 8 matching listings, at most 2 per provider.", "type": "array", "items": { "$ref": "#/components/schemas/DiscoverListingSearchResultOutput" } }, "searchedArea": { "type": "string", "example": "within 10 miles of Seattle, WA", "description": "The area in-person results were kept within; absent for an online or `anywhere` search." }, "areaSource": { "type": "string", "enum": ["named", "saved"], "example": "saved", "description": "Where `searchedArea` came from: `named` when you passed `area` or `neighborhood`, `saved` for your saved ZIP code. Absent with `searchedArea`." }, "ignoredFilters": { "example": ["neighborhood"], "description": "Query parameters the search could not use and ignored, such as an unknown `neighborhood`, a `subcategory` outside its `category`, an `area` that could not be found, or `availableWithin`.", "type": "array", "items": { "type": "string" } }, "widenedFrom": { "type": "string", "example": "Capitol Hill", "description": "The neighborhood that had nothing, when the search widened to its whole region." }, "broadenedFrom": { "description": "When the search found nothing, it searched again with the category alone; these are the filters it dropped.", "allOf": [ { "$ref": "#/components/schemas/DiscoverSearchBroadenedFromOutput" } ] }, "webBusinesses": { "description": "When no listing in the area matched, businesses found on the public web there that are not on Discover, each with an appointment email or phone. Absent when the web search is not configured or the search is online-only.", "type": "array", "items": { "$ref": "#/components/schemas/DiscoverWebBusinessOutput" } } } }, "SearchDiscoverListingsOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SearchDiscoverListingsData" } }, "required": ["status", "data"] }, "CallDiscoverBusinessInput": { "type": "object", "properties": { "businessUrl": { "type": "string", "maxLength": 2048, "description": "The business's URL, exactly as a `search_listings` web business gave it in `webBusinesses[].url`. Only a business found by your own search in the last 24 hours can be called.", "example": "https://barbers.example/book" }, "service": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What to book, in plain words, such as `upright piano full tuning and pitch raise`. Put when the user can come in `timing`, the staff member they asked for in `staff` and their booking details in `notes`. Never put contact details (phone, email, address) in it.", "example": "upright piano full tuning and pitch raise" }, "timing": { "type": "string", "minLength": 1, "maxLength": 120, "description": "When the user can come, in their words, such as `Thursday after 5 or Friday morning`. Leave it out when they named no window. Never put contact details in it.", "example": "Thursday after 5 or Friday morning" }, "staff": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The staff member the user asked for, in their words, such as `Sam`. Leave it out when they named none; never take one from the business's page.", "example": "Sam" }, "notes": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Booking details the user gave for this booking, such as `allergic to lavender`. Only what they said, never contact details. Leave it out when they gave none.", "example": "allergic to lavender" }, "daysFromToday": { "type": "number", "minimum": 0, "maximum": 60, "description": "The day the user asked for, in days from today in their saved time zone: 0 today, 1 tomorrow. Cal asks the business for that date. Leave it out when the user named no day.", "example": 1 }, "callerName": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The name the user gave for themselves, which Cal gives on the call. Leave it out to use the account name; never a name from a search result.", "example": "Jamie Rivera" } }, "required": ["businessUrl", "service"] }, "CallDiscoverBusinessClosedOutput": { "type": "object", "properties": { "nextCallAt": { "type": "string", "nullable": true, "example": "2026-11-13T09:00:00-08:00", "description": "When Cal can next call the business, in its time zone; null when its page lists no time Cal can call in the coming week." }, "timeZone": { "type": "string", "example": "America/Los_Angeles", "description": "The time zone the business's hours are read in." }, "hoursAssumed": { "type": "boolean", "example": false, "description": "True when the business's page publishes no opening hours and Cal used its default weekday hours instead." } }, "required": ["nextCallAt", "timeZone", "hoursAssumed"] }, "CallDiscoverBusinessData": { "type": "object", "properties": { "placed": { "type": "boolean", "example": true, "description": "Whether Cal is calling the business now. When false, `reason` says why." }, "callId": { "type": "string", "example": "call_8f2c1d", "description": "The call's id; set when `placed` is true." }, "callUrl": { "type": "string", "example": "https://app.cal.com/discover/call/call_8f2c1d", "description": "The call's page, with its live transcript and outcome, for the user to follow; set when `placed` is true." }, "reason": { "type": "string", "example": "The assistant cannot call businesses for this account.", "description": "Why no call was placed, in words to pass on to the user; set when `placed` is false. It may name the business's public appointment phone for the user to call themselves, never the user's own details." }, "signInRequired": { "type": "boolean", "enum": [true], "description": "Set when the user must sign in before Cal can call." }, "paymentRequired": { "type": "boolean", "enum": [true], "description": "Set when the user must pick a Discover plan first; `planUrl` is where they pick it." }, "planUrl": { "type": "string", "example": "https://app.cal.com/settings/discover/preferences", "description": "Where the user picks a Discover plan; set with `paymentRequired`." }, "businessClosed": { "description": "Set when Cal did not call because it is outside the business's calling hours. Cal does not schedule calls: tell the user when Cal can call, and call again then if they ask.", "allOf": [ { "$ref": "#/components/schemas/CallDiscoverBusinessClosedOutput" } ] } }, "required": ["placed"] }, "CallDiscoverBusinessOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CallDiscoverBusinessData" } }, "required": ["status", "data"] }, "CreateDiscoverBookingJobInput": { "type": "object", "properties": { "businessUrl": { "type": "string", "maxLength": 2048, "description": "The business's URL, exactly as a `search_listings` web business gave it in `webBusinesses[].url`. Only a business found by your own search in the last 24 hours can be booked.", "example": "https://barbers.example/book" }, "service": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What to book, in plain words, such as `haircut`.", "example": "haircut" }, "area": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The user's area as they gave it: a ZIP code, neighborhood or city.", "example": "Capitol Hill, Seattle" }, "daysFromToday": { "type": "number", "minimum": 0, "maximum": 60, "description": "The day the user asked for, in days from today in their saved time zone: `0` today, `1` tomorrow.", "example": 1 }, "partOfDay": { "enum": ["morning", "afternoon", "evening", "any"], "type": "string", "description": "The part of that day the user asked for, on the business's local clock; `any` when they did not say.", "example": "afternoon" }, "budgetDollars": { "type": "number", "minimum": 1, "maximum": 100000, "description": "The most the user wants to pay for the service, in US dollars, when they said so.", "example": 60 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A key you generate once per booking, such as a UUID. Send the same key to retry the same request: you get its job back, and no second job starts.", "example": "4b7d1c2e-9f0a-4e1b-8c3d-2a6f5e7d9b10" } }, "required": ["businessUrl", "service", "area", "daysFromToday", "partOfDay", "idempotencyKey"] }, "CreateDiscoverBookingJobData": { "type": "object", "properties": { "created": { "type": "boolean", "example": true, "description": "Whether the booking agent started a job. When false, `reason` says why." }, "jobId": { "type": "string", "example": "cm9x1booking0job", "description": "The job's id; set when `created` is true." }, "jobUrl": { "type": "string", "example": "https://app.cal.com/discover/book/cm9x1booking0job", "description": "The job's page, where the user follows its progress, picks an appointment option, approves the price and terms, or cancels; set when `created` is true." }, "reason": { "type": "string", "example": "The assistant cannot book online for this account.", "description": "Why no job was started, in words to pass on to the user; set when `created` is false." }, "signInRequired": { "type": "boolean", "enum": [true], "description": "Set when the user must sign in before a job can start." }, "paymentRequired": { "type": "boolean", "enum": [true], "description": "Set when the user must pick a Discover plan first; `planUrl` is where they pick it." }, "planUrl": { "type": "string", "example": "https://app.cal.com/settings/discover/preferences", "description": "Where the user picks a Discover plan; set with `paymentRequired`." } }, "required": ["created"] }, "CreateDiscoverBookingJobOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CreateDiscoverBookingJobData" } }, "required": ["status", "data"] }, "RecordDiscoverServiceRequestInput": { "type": "object", "properties": { "service": { "type": "string", "minLength": 1, "description": "The service in two or three words, as a provider would list it, such as dentist or piano lessons. Never the user's own words or personal details.", "example": "piano lessons", "maxLength": 80 }, "category": { "type": "string", "description": "The Discover category it belongs to.", "enum": [ "medical", "barbers", "coaching", "consulting", "lessons", "pets", "sports", "dance", "social", "online-services", "saas", "home-services", "other" ], "example": "lessons" }, "subcategory": { "type": "string", "description": "The subcategory slug within that category, when one fits. A subcategory outside the category is ignored.", "example": "music-and-voice", "maxLength": 64, "pattern": "^[a-z0-9-]+$" }, "searchedArea": { "type": "string", "description": "The `searchedArea` a `search_listings` (`GET /v2/discover/listings/search`) result returned when it found nothing, copied as given; it decides the region the request is matched in, and a repeat returns the open request only from the same region. Leave it out when there was none.", "example": "within 10 miles of Seattle, WA", "maxLength": 120 } }, "required": ["service", "category"] }, "RecordDiscoverServiceRequestData": { "type": "object", "properties": { "recorded": { "type": "boolean", "example": true, "description": "Always true: the request is recorded, or the open request for the same need in the same region is returned." }, "service": { "type": "string", "example": "piano lessons", "description": "The service as sent." }, "notify": { "type": "string", "enum": ["account_email"], "example": "account_email", "description": "How the user hears back: an email to their account address when a matching provider joins." }, "matchedProviders": { "enum": ["nearby_and_online", "nearby", "online_only", "none"], "type": "string", "example": "nearby", "description": "Which new providers can trigger the email. `nearby_and_online`: providers in the user's launch region, and online providers in this online-friendly category (coaching, consulting, online services, software). `nearby`: providers in the user's launch region. `online_only`: only online providers, because the request is outside every launch region. `none`: no provider can, because the request is outside every launch region in a category booked in person; search the user's area with `GET /v2/discover/listings/search` and record it again with its `searchedArea`." } }, "required": ["recorded", "service", "notify", "matchedProviders"] }, "RecordDiscoverServiceRequestOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/RecordDiscoverServiceRequestData" } }, "required": ["status", "data"] }, "ConferencingAppsWithDefaultOutputDto": { "type": "object", "properties": { "id": { "type": "number", "description": "Id of the conferencing app credentials" }, "type": { "type": "string", "example": "google_video", "description": "Type of conferencing app" }, "userId": { "type": "number", "description": "Id of the user associated to the conferencing app" }, "invalid": { "type": "boolean", "nullable": true, "example": true, "description": "Whether if the connection is working or not." }, "appSlug": { "type": "string", "example": "google-meet", "description": "Slug of the conferencing app" }, "isDefault": { "type": "boolean", "example": false, "description": "Whether this app is the user's default conferencing app" } }, "required": ["id", "type", "userId", "appSlug", "isDefault"] }, "ConferencingAppsWithDefaultOutputResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConferencingAppsWithDefaultOutputDto" } } }, "required": ["status", "data"] }, "SetDefaultConferencingAppInput": { "type": "object", "properties": { "appSlug": { "type": "string", "description": "The slug of the conferencing app to set as default", "example": "google-meet", "enum": ["google-meet", "zoom", "msteams", "daily-video"] } }, "required": ["appSlug"] }, "ReportOrgBookingInput": { "type": "object", "properties": { "bookingUid": { "type": "string", "description": "The UID of the booking to report", "example": "booking-uid-123" }, "reason": { "enum": ["SPAM", "UNWANTED", "DONT_KNOW_PERSON", "OTHER"], "type": "string", "description": "The reason for reporting the booking", "example": "SPAM" }, "description": { "type": "string", "description": "Additional description for the report" }, "reportType": { "enum": ["EMAIL", "DOMAIN"], "type": "string", "description": "Whether to report by email or domain. EMAIL targets the specific booker email. DOMAIN targets all emails from the same domain.", "example": "EMAIL" } }, "required": ["bookingUid", "reason", "reportType"] }, "ReportOrgBookingData": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "description": "A human-readable message describing the result", "example": "Booking reported and cancelled successfully" }, "bookingUid": { "type": "string", "description": "The UID of the reported booking", "example": "booking-uid-123" }, "reportedCount": { "type": "number", "description": "The number of booking reports created", "example": 1 }, "cancelledCount": { "type": "number", "description": "The number of bookings cancelled", "example": 3 } }, "required": ["success", "message", "bookingUid", "reportedCount", "cancelledCount"] }, "ReportOrgBookingOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ReportOrgBookingData" } }, "required": ["status", "data"] }, "BlockOrgBookingInput": { "type": "object", "properties": { "bookingUid": { "type": "string", "description": "The UID of the booking whose attendee should be blocked", "example": "booking-uid-123" }, "blockType": { "enum": ["EMAIL", "DOMAIN"], "type": "string", "description": "Whether to block by email or domain. EMAIL blocks the specific booker email. DOMAIN blocks all emails from the same domain.", "example": "EMAIL" } }, "required": ["bookingUid", "blockType"] }, "BlockOrgBookingData": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "description": "A human-readable message describing the result", "example": "Added to blocklist and 3 bookings cancelled" }, "bookingUid": { "type": "string", "description": "The UID of the booking whose attendee was blocked", "example": "booking-uid-123" }, "cancelledCount": { "type": "number", "description": "The number of bookings cancelled", "example": 3 }, "blockedValue": { "type": "string", "description": "The email or domain that was added to the blocklist", "example": "spammer@example.com" } }, "required": ["success", "message", "bookingUid", "cancelledCount", "blockedValue"] }, "BlockOrgBookingOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/BlockOrgBookingData" } }, "required": ["status", "data"] }, "RequestEmailVerificationInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email to verify.", "example": "acme@example.com" } }, "required": ["email"] }, "RequestEmailVerificationOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] } }, "required": ["status"] }, "RequestPhoneVerificationInput": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone number to verify.", "example": "+372 5555 6666" } }, "required": ["phone"] }, "RequestPhoneVerificationOutput": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] } }, "required": ["status"] }, "VerifyEmailInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email to verify.", "example": "example@acme.com" }, "code": { "type": "string", "description": "verification code sent to the email to verify", "example": "1ABG2C" } }, "required": ["email", "code"] }, "UserVerifiedEmailOutputData": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier for the verified email.", "example": 789 }, "email": { "type": "string", "description": "The verified email address.", "example": "user@example.com", "format": "email" }, "userId": { "type": "number", "description": "The ID of the associated user, if applicable.", "example": 45 } }, "required": ["id", "email", "userId"] }, "UserVerifiedEmailOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UserVerifiedEmailOutputData" } }, "required": ["status", "data"] }, "VerifyPhoneInput": { "type": "object", "properties": { "phone": { "type": "string", "description": "phone number to verify.", "example": "+37255556666" }, "code": { "type": "string", "description": "verification code sent to the phone number to verify", "example": "1ABG2C" } }, "required": ["phone", "code"] }, "UserVerifiedPhoneOutputData": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier for the verified email.", "example": 789 }, "phoneNumber": { "type": "string", "description": "The verified phone number.", "example": "+37255556666", "format": "phone" }, "userId": { "type": "number", "description": "The ID of the associated user, if applicable.", "example": 45 } }, "required": ["id", "phoneNumber", "userId"] }, "UserVerifiedPhoneOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/UserVerifiedPhoneOutputData" } }, "required": ["status", "data"] }, "UserVerifiedEmailsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserVerifiedEmailOutputData" } } }, "required": ["status", "data"] }, "UserVerifiedPhonesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserVerifiedPhoneOutputData" } } }, "required": ["status", "data"] }, "TeamVerifiedEmailOutputData": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier for the verified email.", "example": 789 }, "email": { "type": "string", "description": "The verified email address.", "example": "user@example.com", "format": "email" }, "teamId": { "type": "number", "description": "The ID of the associated team, if applicable.", "example": 89 }, "userId": { "type": "number", "nullable": true, "description": "The ID of the associated user, if applicable.", "example": 45 } }, "required": ["id", "email", "teamId"] }, "TeamVerifiedEmailOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamVerifiedEmailOutputData" } }, "required": ["status", "data"] }, "TeamVerifiedPhoneOutputData": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier for the verified email.", "example": 789 }, "phoneNumber": { "type": "string", "description": "The verified phone number.", "example": "+37255556666", "format": "phone" }, "userId": { "type": "number", "nullable": true, "description": "The ID of the associated user, if applicable.", "example": 45 }, "teamId": { "type": "number", "description": "The ID of the associated team, if applicable.", "example": 89 } }, "required": ["id", "phoneNumber", "teamId"] }, "TeamVerifiedPhoneOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TeamVerifiedPhoneOutputData" } }, "required": ["status", "data"] }, "TeamVerifiedEmailsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamVerifiedEmailOutputData" } } }, "required": ["status", "data"] }, "TeamVerifiedPhonesOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamVerifiedPhoneOutputData" } } }, "required": ["status", "data"] }, "BookingLimitPoolEventTypeOutput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" } }, "required": ["id", "title"] }, "BookingLimitPoolOutput": { "type": "object", "properties": { "perDay": { "type": "number", "nullable": true, "example": 4 }, "perWeek": { "type": "number", "nullable": true, "example": 20 }, "perMonth": { "type": "number", "nullable": true, "example": 60 }, "perYear": { "type": "number", "nullable": true, "example": 500 }, "id": { "type": "string", "format": "uuid" }, "teamId": { "type": "number" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": ["SHARED", "PER_EVENT"] }, "archived": { "type": "boolean", "readOnly": true, "description": "An archived pool is skipped by enforcement until it is restored." }, "eventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/BookingLimitPoolEventTypeOutput" } } }, "required": [ "perDay", "perWeek", "perMonth", "perYear", "id", "teamId", "name", "mode", "archived", "eventTypes" ] }, "BookingLimitPoolCandidateOutput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "poolId": { "type": "string", "nullable": true, "format": "uuid", "description": "The pool this event type is in, if any." } }, "required": ["id", "title", "poolId"] }, "BookingLimitPoolsData": { "type": "object", "properties": { "pools": { "type": "array", "items": { "$ref": "#/components/schemas/BookingLimitPoolOutput" } }, "eventTypes": { "description": "The team's round-robin event types that can be in a pool.", "type": "array", "items": { "$ref": "#/components/schemas/BookingLimitPoolCandidateOutput" } } }, "required": ["pools", "eventTypes"] }, "BookingLimitPoolsOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/BookingLimitPoolsData" } }, "required": ["status", "data"] }, "CreateBookingLimitPoolInput": { "type": "object", "properties": { "perDay": { "type": "number", "nullable": true, "minimum": 1, "example": 2 }, "perWeek": { "type": "number", "nullable": true, "minimum": 1, "example": 5 }, "perMonth": { "type": "number", "nullable": true, "minimum": 1 }, "perYear": { "type": "number", "nullable": true, "minimum": 1 }, "name": { "type": "string", "minLength": 1, "example": "Engineering interviews" }, "mode": { "type": "string", "enum": ["SHARED", "PER_EVENT"], "description": "SHARED: each host has one allowance across every event in the pool. PER_EVENT: the same allowance applies to each event separately." }, "eventTypeIds": { "uniqueItems": true, "minItems": 1, "maxItems": 10000, "example": ["0bce7b70-d7f0-4e5f-bcce-2f41b6fd5116", "15314c7c-11a0-440d-9ae9-23593c193a2b"], "description": "Round-robin event type UUIDs of the team (short UUIDs accepted). Each event type can be in one pool. Legacy numeric IDs require organization access.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": ["name", "mode", "eventTypeIds"] }, "BookingLimitPoolResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/BookingLimitPoolOutput" } }, "required": ["status", "data"] }, "UpdateBookingLimitPoolInput": { "type": "object", "properties": { "perDay": { "type": "number", "nullable": true, "minimum": 1, "example": 2 }, "perWeek": { "type": "number", "nullable": true, "minimum": 1, "example": 5 }, "perMonth": { "type": "number", "nullable": true, "minimum": 1 }, "perYear": { "type": "number", "nullable": true, "minimum": 1 }, "name": { "type": "string", "minLength": 1, "example": "Engineering interviews" }, "mode": { "type": "string", "enum": ["SHARED", "PER_EVENT"], "description": "Changing the mode keeps every host's own limit." }, "eventTypeIds": { "uniqueItems": true, "minItems": 1, "maxItems": 10000, "example": ["0bce7b70-d7f0-4e5f-bcce-2f41b6fd5116", "15314c7c-11a0-440d-9ae9-23593c193a2b"], "description": "Replaces the pool's event type UUIDs (short UUIDs accepted). Legacy numeric IDs require organization access.", "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "BookingLimitPoolHostOutput": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "hostLimit": { "nullable": true, "description": "The host's own limits; null while every interval uses the pool's limits.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLimitsOutput" } ] }, "effectiveLimit": { "description": "The limits enforced for this host.", "allOf": [ { "$ref": "#/components/schemas/BookingLimitsOutput" } ] } }, "required": ["userId", "hostLimit", "effectiveLimit"] }, "BookingLimitPoolHostsData": { "type": "object", "properties": { "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingLimitPoolHostOutput" } }, "nextCursor": { "type": "string", "nullable": true, "format": "uuid", "description": "Pass as `cursor` to fetch the next page; null on the last page." } }, "required": ["hosts", "nextCursor"] }, "BookingLimitPoolHostsOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/BookingLimitPoolHostsData" } }, "required": ["status", "data"] }, "BookingLimitsPatchInput": { "type": "object", "properties": { "perDay": { "type": "number", "nullable": true, "minimum": 1, "example": 2 }, "perWeek": { "type": "number", "nullable": true, "minimum": 1, "example": 5 }, "perMonth": { "type": "number", "nullable": true, "minimum": 1 }, "perYear": { "type": "number", "nullable": true, "minimum": 1 } } }, "UpdateBookingLimitPoolHostInput": { "type": "object", "properties": { "hostLimit": { "description": "The intervals to change; an omitted interval is left alone and null returns it to the pool's limit.", "allOf": [ { "$ref": "#/components/schemas/BookingLimitsPatchInput" } ] } }, "required": ["hostLimit"] }, "BookingLimitPoolHostResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/BookingLimitPoolHostOutput" } }, "required": ["status", "data"] }, "SetBookingLimitPoolHostInput": { "type": "object", "properties": { "hostLimit": { "description": "The host's complete limit; an omitted or null interval uses the pool's limit, and an empty object clears the host's own limit.", "allOf": [ { "$ref": "#/components/schemas/BookingLimitsPatchInput" } ] } }, "required": ["hostLimit"] }, "EventTypeSequenceSegmentInput": { "type": "object", "properties": { "eventTypeId": { "type": "number", "minimum": 1, "example": 101, "description": "A collective or round-robin event type of the team. It can't be seated, recurring, paid or a managed event type." } }, "required": ["eventTypeId"] }, "CreateEventTypeSequenceInput": { "type": "object", "properties": { "title": { "type": "string", "example": "Engineering interview loop", "maxLength": 255 }, "slug": { "type": "string", "example": "engineering-loop", "maxLength": 255, "description": "Slugified like an event type slug. Must not be the slug of another sequence or event type of the team." }, "description": { "type": "string", "example": "Three back-to-back interviews.", "maxLength": 3000 }, "segments": { "minItems": 2, "maxItems": 5, "description": "The event types in booking order; they run back to back, at most 8 hours in total. The same round-robin event type can be used for two segments, but a person can be a fixed host of only one segment.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeSequenceSegmentInput" } } }, "required": ["title", "slug", "segments"] }, "EventTypeSequenceHostOutput": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Dana Smith" }, "avatarUrl": { "type": "string", "nullable": true } }, "required": ["name", "avatarUrl"] }, "EventTypeSequenceSegmentOutput": { "type": "object", "properties": { "position": { "type": "number", "example": 0, "description": "0-based place in booking order." }, "eventTypeId": { "type": "number", "example": 101 }, "title": { "type": "string", "nullable": true, "example": "Technical interview", "description": "Null when the event type was deleted." }, "lengthMinutes": { "type": "number", "nullable": true, "example": 45 }, "schedulingType": { "nullable": true, "enum": ["collective", "roundRobin", "managed"], "type": "string" }, "fixedHosts": { "description": "Every host of a collective segment, or the fixed hosts of a round-robin segment.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeSequenceHostOutput" } }, "invalidReason": { "nullable": true, "enum": [ "not_found", "managed_parent", "unsupported_scheduling_type", "seated", "recurring", "paid", "multiple_host_groups", "no_hosts", "fixed_host_in_several_segments", "question_conflict", "block_too_long" ], "type": "string", "description": "Why this segment can't be booked as part of the sequence right now, from its event type as it is now; null when it can." } }, "required": [ "position", "eventTypeId", "title", "lengthMinutes", "schedulingType", "fixedHosts", "invalidReason" ] }, "EventTypeSequenceOutput": { "type": "object", "properties": { "uid": { "type": "string", "format": "uuid" }, "teamId": { "type": "number" }, "title": { "type": "string", "example": "Engineering interview loop" }, "slug": { "type": "string", "example": "engineering-loop" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["valid", "invalid"], "description": "Checked against the segments' event types on every read. An invalid sequence can't be booked, and its public page is not found." }, "totalLengthMinutes": { "type": "number", "example": 135 }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeSequenceSegmentOutput" } }, "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "Each segment's booking fields merged by slug, without the location." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uid", "teamId", "title", "slug", "description", "status", "totalLengthMinutes", "segments", "bookingFields", "createdAt", "updatedAt" ] }, "EventTypeSequenceResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/EventTypeSequenceOutput" } }, "required": ["status", "data"] }, "EventTypeSequencesData": { "type": "object", "properties": { "sequences": { "description": "In creation order.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeSequenceOutput" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` to fetch the next page; null on the last page." } }, "required": ["sequences", "nextCursor"] }, "EventTypeSequencesOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/EventTypeSequencesData" } }, "required": ["status", "data"] }, "UpdateEventTypeSequenceInput": { "type": "object", "properties": { "title": { "type": "string", "example": "Engineering interview loop", "maxLength": 255 }, "slug": { "type": "string", "example": "engineering-loop", "maxLength": 255, "description": "Must not be the slug of another sequence or event type of the team." }, "description": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Null removes the description." }, "segments": { "minItems": 2, "maxItems": 5, "description": "Replaces every segment, in booking order. Loops already booked keep their bookings. When left out, the segments are not checked again, so a sequence that reads as invalid can still be renamed.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeSequenceSegmentInput" } } } }, "PublicEventTypeSequenceSegmentOutput": { "type": "object", "properties": { "position": { "type": "number", "example": 0, "description": "0-based place in booking order." }, "title": { "type": "string", "example": "Technical interview" }, "lengthMinutes": { "type": "number", "example": 45 }, "schedulingType": { "enum": ["collective", "roundRobin"], "type": "string" }, "fixedHosts": { "description": "Who the segment is with: every host of a collective segment. Empty for a round-robin segment, whose host is picked from its pool when booking, and for a private team.", "type": "array", "items": { "$ref": "#/components/schemas/EventTypeSequenceHostOutput" } } }, "required": ["position", "title", "lengthMinutes", "schedulingType", "fixedHosts"] }, "PublicEventTypeSequenceOutput": { "type": "object", "properties": { "uid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "Engineering interview loop" }, "description": { "type": "string", "nullable": true }, "totalLengthMinutes": { "type": "number", "example": 135, "description": "The segments run back to back." }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/PublicEventTypeSequenceSegmentOutput" } }, "bookingFields": { "type": "array", "items": { "discriminator": { "propertyName": "field" }, "oneOf": [ { "title": "Default Name", "discriminator": { "propertyName": "variant" }, "oneOf": [ { "title": "Default Full Name", "$ref": "#/components/schemas/SystemFullNameFieldOutput_2026_06_12" }, { "title": "Default Split Name", "$ref": "#/components/schemas/SystemSplitNameFieldOutput_2026_06_12" } ] }, { "title": "Default Email", "$ref": "#/components/schemas/SystemEmailFieldOutput_2026_06_12" }, { "title": "Default Location", "$ref": "#/components/schemas/SystemLocationFieldOutput_2026_06_12" }, { "title": "Default Title", "$ref": "#/components/schemas/SystemTitleFieldOutput_2026_06_12" }, { "title": "Default Notes", "$ref": "#/components/schemas/SystemNotesFieldOutput_2026_06_12" }, { "title": "Default Guests", "$ref": "#/components/schemas/SystemGuestsFieldOutput_2026_06_12" }, { "title": "Default Reschedule Reason", "$ref": "#/components/schemas/SystemRescheduleReasonFieldOutput_2026_06_12" }, { "title": "Default Attendee Phone", "$ref": "#/components/schemas/SystemAttendeePhoneFieldOutput_2026_06_12" }, { "title": "Workflow-added SMS Reminder", "$ref": "#/components/schemas/SystemSmsReminderFieldOutput_2026_06_12" }, { "title": "Workflow-added AI Agent Phone", "$ref": "#/components/schemas/SystemAiAgentPhoneFieldOutput_2026_06_12" }, { "title": "Custom Booking Field", "discriminator": { "propertyName": "type" }, "oneOf": [ { "title": "Custom Email", "$ref": "#/components/schemas/CustomEmailFieldOutput_2026_06_12" }, { "title": "Custom Phone", "$ref": "#/components/schemas/CustomPhoneFieldOutput_2026_06_12" }, { "title": "Custom Address", "$ref": "#/components/schemas/CustomAddressFieldOutput_2026_06_12" }, { "title": "Custom Short Text", "$ref": "#/components/schemas/CustomShortTextFieldOutput_2026_06_12" }, { "title": "Custom Number", "$ref": "#/components/schemas/CustomNumberFieldOutput_2026_06_12" }, { "title": "Custom Long Text", "$ref": "#/components/schemas/CustomLongTextFieldOutput_2026_06_12" }, { "title": "Custom Select", "$ref": "#/components/schemas/CustomSelectFieldOutput_2026_06_12" }, { "title": "Custom Multi-Select", "$ref": "#/components/schemas/CustomMultiSelectFieldOutput_2026_06_12" }, { "title": "Custom Multiple Emails", "$ref": "#/components/schemas/CustomMultiEmailFieldOutput_2026_06_12" }, { "title": "Custom Checkbox Group", "$ref": "#/components/schemas/CustomCheckboxGroupFieldOutput_2026_06_12" }, { "title": "Custom Radio Group", "$ref": "#/components/schemas/CustomRadioGroupFieldOutput_2026_06_12" }, { "title": "Custom Checkbox", "$ref": "#/components/schemas/CustomCheckboxFieldOutput_2026_06_12" }, { "title": "Custom URL", "$ref": "#/components/schemas/CustomUrlFieldOutput_2026_06_12" } ] }, { "title": "Unknown Booking Field", "$ref": "#/components/schemas/UnknownBookingFieldOutput_2026_06_12" } ] }, "description": "The questions the booker answers once for the whole sequence: each segment's booking fields merged by slug, without the location." } }, "required": ["uid", "title", "description", "totalLengthMinutes", "segments", "bookingFields"] }, "PublicEventTypeSequenceResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "$ref": "#/components/schemas/PublicEventTypeSequenceOutput" } }, "required": ["status", "data"] }, "Slot_2024_09_04": { "type": "object", "properties": { "start": { "type": "string", "description": "Start time of slot." } }, "required": ["start"] }, "GetSequenceSlotsResponseOutput": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string" }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Slot_2024_09_04" } }, "description": "Start times at which every segment fits back to back, grouped by day (`YYYY-MM-DD`) in the requested time zone. Each start is when the first segment begins. Empty for a sequence that can't be booked right now.", "example": { "2033-09-05": [ { "start": "2033-09-05T09:00:00.000+02:00" }, { "start": "2033-09-05T09:30:00.000+02:00" } ], "2033-09-06": [ { "start": "2033-09-06T09:00:00.000+02:00" } ] } } }, "required": ["status", "data"] }, "RegisterAppPushSubscriptionInput": { "type": "object", "properties": { "token": { "type": "string", "description": "Expo Push Token", "example": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" }, "platform": { "type": "string", "enum": ["IOS", "ANDROID"], "description": "Mobile platform", "example": "IOS" }, "deviceId": { "type": "string", "description": "Unique device identifier", "example": "device-uuid-123" } }, "required": ["token", "platform", "deviceId"] }, "AppPushSubscriptionOutputDto": { "type": "object", "properties": { "id": { "type": "number" }, "userId": { "type": "number" }, "type": { "type": "string" }, "platform": { "type": "string" }, "identifier": { "type": "string" }, "deviceId": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": ["id", "userId", "type", "platform", "identifier", "deviceId", "createdAt", "updatedAt"] }, "AppPushSubscriptionResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AppPushSubscriptionOutputDto" } }, "required": ["status", "data"] }, "RemoveAppPushSubscriptionInput": { "type": "object", "properties": { "token": { "type": "string", "description": "Expo Push Token to remove", "example": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" } }, "required": ["token"] }, "RemoveAppPushSubscriptionResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "message": { "type": "string", "example": "App push subscription removed successfully" } }, "required": ["status", "message"] }, "ChatPushLinkIntentOutputDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Opaque one-time token for Companion" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the one-time token expires" } }, "required": ["token", "expiresAt"] }, "ChatPushLinkIntentResponseDto": { "type": "object", "properties": { "status": { "enum": ["success"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ChatPushLinkIntentOutputDto" } }, "required": ["status", "data"] }, "RemoveSlackSubscriptionInput": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Slack user ID", "example": "U0123456789" }, "teamId": { "type": "string", "description": "Slack team (workspace) ID", "example": "T0123456789" }, "subscriptionId": { "type": "number", "minimum": 1, "description": "Delete only this subscription ID; requires subscriptionVersion" }, "subscriptionVersion": { "type": "string", "description": "Delete only this generation; requires subscriptionId" } }, "required": ["identifier", "teamId"] }, "RemoveSlackSubscriptionResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "message": { "type": "string", "example": "Slack subscription removed successfully" } }, "required": ["status", "message"] }, "RemoveChatSubscriptionInput": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Chat platform identifier to remove", "example": "U0123456789" }, "subscriptionId": { "type": "number", "minimum": 1, "description": "Delete only this subscription ID; requires subscriptionVersion" }, "subscriptionVersion": { "type": "string", "description": "Delete only this generation; requires subscriptionId" } }, "required": ["identifier"] }, "RemoveTelegramSubscriptionResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "message": { "type": "string", "example": "Telegram subscription removed successfully" } }, "required": ["status", "message"] }, "RemoveImessageSubscriptionResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "enum": ["success", "error"] }, "message": { "type": "string", "example": "iMessage subscription removed successfully" } }, "required": ["status", "message"] }, "AgentChannelsOutputDto": { "type": "object", "properties": { "slack": { "type": "boolean", "example": true }, "telegram": { "type": "boolean", "example": true }, "imessage": { "type": "boolean", "example": true } }, "required": ["slack", "telegram", "imessage"] }, "AgentChannelsResponseDto": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AgentChannelsOutputDto" } }, "required": ["status", "data"] }, "UpdateAgentChannelInput": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } }, "required": ["enabled"] }, "AllowlistServiceOutput": { "type": "object", "properties": { "direction": { "enum": ["ingress-to-cal", "egress-from-cal"], "type": "string", "description": "`ingress-to-cal` are the addresses your systems connect to when they call Cal.com. `egress-from-cal` are the addresses Cal.com connects to your systems from, for example when delivering a webhook.", "example": "egress-from-cal" }, "ipv4": { "example": ["203.0.113.20/32", "203.0.113.21/32"], "type": "array", "items": { "type": "string" } } }, "required": ["direction", "ipv4"] }, "AllowlistMetadataOutput": { "type": "object", "properties": { "schemaVersion": { "type": "string", "example": "v1" } }, "required": ["schemaVersion"] }, "AllowlistServicesData": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/AllowlistMetadataOutput" }, "services": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AllowlistServiceOutput" }, "description": "Allowlists keyed by service name." } }, "required": ["metadata", "services"] }, "GetAllowlistsOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AllowlistServicesData" } }, "required": ["status", "data"] }, "NamedAllowlistServiceOutput": { "type": "object", "properties": { "direction": { "enum": ["ingress-to-cal", "egress-from-cal"], "type": "string", "description": "`ingress-to-cal` are the addresses your systems connect to when they call Cal.com. `egress-from-cal` are the addresses Cal.com connects to your systems from, for example when delivering a webhook.", "example": "egress-from-cal" }, "ipv4": { "example": ["203.0.113.20/32", "203.0.113.21/32"], "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "example": "webhooks" } }, "required": ["direction", "ipv4", "name"] }, "AllowlistServiceData": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/AllowlistMetadataOutput" }, "service": { "$ref": "#/components/schemas/NamedAllowlistServiceOutput" } }, "required": ["metadata", "service"] }, "GetAllowlistOutput": { "type": "object", "properties": { "status": { "enum": ["success", "error"], "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AllowlistServiceData" } }, "required": ["status", "data"] } } } }