openapi: 3.2.0 info: title: Zoho CRM Holidays API description: Manage business and shift holidays in Zoho CRM. This API allows you to create, retrieve, update, and delete holidays that affect business hours and shift schedules. Business holidays apply to all users while shift holidays apply to specific shift configurations. version: '8' servers: - url: https://zohoapis.{dc}/crm/{version} description: API Server URL variables: dc: enum: - com - eu - in - cn - au default: com description: API Server URL TLD version: enum: - v8 default: v8 description: API version security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.READ - ZohoCRM.settings.business_hours.CREATE - ZohoCRM.settings.business_hours.UPDATE - ZohoCRM.settings.business_hours.DELETE tags: - name: Holidays description: Operations for managing holidays that affect business hours and shift schedules paths: /settings/holidays: get: tags: - Holidays summary: Retrieve holidays description: Retrieves a list of holidays filtered by year, type (business or shift), and shift ID. Business holidays apply organization-wide, while shift holidays are specific to configured shifts. Returns paginated results with metadata. security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.READ operationId: getHolidays parameters: - $ref: '#/components/parameters/Year' - $ref: '#/components/parameters/Type' - $ref: '#/components/parameters/ShiftId' responses: '200': description: Success - Returns a paginated list of holidays matching the specified filter criteria content: application/json: schema: type: object properties: holidays: type: array description: Array of holiday objects matching the filter criteria items: type: object properties: name: type: string description: 'Name of the holiday. Cannot contain special characters: #, %, ^, &, *' maxLength: 80 minLength: 1 pattern: ^[^#%^&*]+$ date: type: string format: date description: Date of the holiday in YYYY-MM-DD format. Must be within current or next financial year. type: type: string description: 'Type of holiday: business_holiday applies to all users, shift_holiday applies to specific shifts' enum: - business_holiday - shift_holiday shift_hour: type: - object - 'null' description: Shift hour configuration associated with this holiday (required for shift_holiday type) properties: name: type: string description: Name of the shift hour maxLength: 255 id: type: string description: Unique identifier of the shift hour pattern: ^[0-9]+$ maxLength: 255 required: - name - id additionalProperties: false id: type: string description: Unique identifier of the holiday pattern: ^[0-9]+$ maxLength: 255 year: type: integer format: int32 description: Year of the holiday minimum: 2000 maximum: 2100 required: - name - date - type - shift_hour - id - year description: The Item of the object. additionalProperties: false maxItems: 100 info: type: object description: Pagination metadata for the response properties: per_page: type: integer format: int32 description: Number of records returned per page minimum: 1 page: type: integer format: int32 description: Current page number (1-indexed) minimum: 1 count: type: integer format: int32 description: Total number of records returned in this response minimum: 0 more_records: type: boolean description: Indicates whether more records are available on subsequent pages additionalProperties: false required: - holidays description: The Response body of the object. additionalProperties: false '204': description: No Content - No holidays found matching the specified filter criteria '400': description: Bad request - validation errors content: application/json: schema: type: object properties: code: type: string enum: - PATTERN_NOT_MATCHED description: The Code of the object. details: type: object description: The Details of the object. additionalProperties: true message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - error description: The Status of the object. description: The Response body of the object. additionalProperties: false post: tags: - Holidays summary: Create holidays description: Creates one or more holidays with specified names, dates, types, and associated shift hours. Each holiday must have a unique name and date combination. Business holidays apply to all users, while shift holidays require a valid shift_hour association. security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.CREATE operationId: createHolidays requestBody: description: Request body containing an array of holidays to create. Each holiday must include a name, date, type, and shift_hour association (for shift holidays). content: application/json: schema: type: object properties: holidays: type: array description: Array of holiday objects to create. Maximum 52 holidays allowed per type per year. minItems: 1 items: type: object properties: name: type: string description: 'Name of the holiday. Cannot contain special characters: #, %, ^, &, *' maxLength: 80 minLength: 1 pattern: ^[^#%^&*]+$ date: type: string format: date description: Date of the holiday in YYYY-MM-DD format. Must be within current or next financial year. type: type: string description: 'Type of holiday: business_holiday applies to all users, shift_holiday applies to specific shifts' enum: - business_holiday - shift_holiday shift_hour: type: object description: Shift hour association (required when type is shift_holiday, should be null or omitted for business_holiday) properties: name: type: string description: Name of the shift hour maxLength: 255 id: type: string description: Unique identifier of the shift hour pattern: ^[0-9]+$ maxLength: 255 required: - name - id additionalProperties: false required: - name - date - type - shift_hour description: The Item of the object. additionalProperties: false maxItems: 100 info: type: object properties: per_page: type: integer format: int32 description: The Per page of the object. page: type: integer format: int32 description: The Page of the object. count: type: integer format: int32 description: The Count of the object. more_records: type: boolean description: The More records of the object. description: The Info of the object. additionalProperties: false description: The Request body of the object. additionalProperties: false required: true responses: '201': description: Holidays created successfully content: application/json: schema: type: object properties: holidays: type: array items: type: object properties: code: type: string enum: - SUCCESS description: The Code of the object. details: type: object properties: id: type: string description: The unique identifier of the holiday maxLength: 255 description: The Details of the object. additionalProperties: false message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - success description: The Status of the object. required: - code - details - message - status description: The Item of the object. additionalProperties: false description: The Holidays of the object. maxItems: 100 required: - holidays description: The Response body of the object. additionalProperties: false '400': description: Bad request - validation errors content: application/json: schema: type: object properties: holidays: type: array items: type: object properties: code: type: string enum: - MANDATORY_NOT_FOUND - LIMIT_EXCEEDED - DUPLICATE_DATA - DEPENDENT_FIELD_MISSING - INVALID_DATA description: The Code of the object. details: type: object description: The Details of the object. additionalProperties: true message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - error description: The Status of the object. description: The Item of the object. additionalProperties: false description: The Holidays of the object. maxItems: 100 description: The Response body of the object. additionalProperties: false '403': $ref: '#/components/responses/ForbiddenError' put: tags: - Holidays summary: Update holidays (bulk) description: Updates one or more existing holidays by their IDs with new names, dates, or shift hour associations. security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.UPDATE operationId: updateHolidays requestBody: description: Request body containing an array of holidays to update. Each holiday must include its ID along with the fields to update. content: application/json: schema: oneOf: - type: object properties: holidays: type: array description: Array of holiday objects to update with their IDs and new values minItems: 1 items: type: object properties: name: type: string description: 'Name of the holiday. Cannot contain special characters: #, %, ^, &, *' maxLength: 80 minLength: 1 pattern: ^[^#%^&*]+$ date: type: string format: date description: Date of the holiday in YYYY-MM-DD format. Must be within current or next financial year. type: type: string description: 'Type of holiday: business_holiday applies to all users, shift_holiday applies to specific shifts' enum: - business_holiday - shift_holiday shift_hour: type: object description: Shift hour association (required when type is shift_holiday) properties: name: type: string description: Name of the shift hour maxLength: 255 id: type: string description: Unique identifier of the shift hour pattern: ^[0-9]+$ maxLength: 255 required: - name - id additionalProperties: false id: type: string description: Unique identifier of the holiday to update pattern: ^[0-9]+$ maxLength: 255 required: - name - date - type - shift_hour - id description: The Item of the object. additionalProperties: false maxItems: 100 info: type: object properties: per_page: type: integer format: int32 description: The Per page of the object. page: type: integer format: int32 description: The Page of the object. count: type: integer format: int32 description: The Count of the object. more_records: type: boolean description: The More records of the object. description: The Info of the object. additionalProperties: false description: A object value. additionalProperties: false description: The Request body of the object. required: true responses: '200': description: Success - Holidays updated successfully. Returns array of result objects with status for each holiday. content: application/json: schema: type: object properties: holidays: type: array description: Array of operation results for each holiday update request items: type: object properties: code: type: string description: Result code indicating success or failure maxLength: 255 details: type: object description: Additional details about the operation result properties: id: type: string description: The ID of the updated holiday maxLength: 255 additionalProperties: false message: type: string description: Human-readable message describing the result maxLength: 255 status: type: string description: Operation status maxLength: 255 description: The Item of the object. additionalProperties: false maxItems: 100 required: - holidays description: The Response body of the object. additionalProperties: false '400': description: Bad request - validation errors content: application/json: schema: type: object properties: holidays: type: array items: type: object properties: code: type: string enum: - DUPLICATE_DATA - DEPENDENT_FIELD_MISSING - INVALID_DATA description: The Code of the object. details: type: object description: The Details of the object. additionalProperties: true message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - error description: The Status of the object. description: The Item of the object. additionalProperties: false description: The Holidays of the object. maxItems: 100 description: The Response body of the object. additionalProperties: false '403': $ref: '#/components/responses/ForbiddenError' /settings/holidays/{holidayId}: put: tags: - Holidays summary: Update a specific holiday description: 'Updates a specific holiday identified by its ID. You can modify the holiday''s name (max 80 characters, no special characters: #, %, ^, &, *) or date (must be within current or next financial year). Provide only the fields you want to update.' security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.UPDATE operationId: updateHoliday parameters: - $ref: '#/components/parameters/HolidayId' requestBody: description: Request body containing the fields to update for the holiday. Provide only the fields you wish to change. content: application/json: schema: type: object properties: holidays: type: array description: Array containing a single holiday object with fields to update minItems: 1 maxItems: 1 items: type: object properties: name: type: - string - 'null' description: 'New name for the holiday. Cannot contain special characters: #, %, ^, &, *. Set to null to keep existing value.' maxLength: 80 minLength: 1 pattern: ^[^#%^&*]+$ date: type: - string - 'null' format: date description: New date for the holiday in YYYY-MM-DD format. Must be within current or next financial year. Set to null to keep existing value. description: The Item of the object. additionalProperties: false description: The Request body of the object. additionalProperties: false required: true responses: '200': description: Holiday updated successfully content: application/json: schema: type: object properties: holidays: type: array items: type: object properties: code: type: string enum: - SUCCESS description: The Code of the object. details: type: object properties: id: type: string description: The unique identifier of the holiday maxLength: 255 description: The Details of the object. additionalProperties: false message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - success description: The Status of the object. required: - code - details - message - status description: The Item of the object. additionalProperties: false description: The Holidays of the object. maxItems: 100 required: - holidays description: The Response body of the object. additionalProperties: false '400': description: Bad request - validation errors content: application/json: schema: oneOf: - type: object additionalProperties: false description: Error response for multiple business hours creation attempt properties: holidays: type: array items: $ref: '#/components/schemas/InvalidDataResponse' description: The Holidays of the array inside error object. maxItems: 100 required: - holidays - $ref: '#/components/schemas/InvalidDataResponse' get: tags: - Holidays summary: Retrieve a specific holiday description: Retrieves complete details of a specific holiday by its unique identifier, including its name, date, type, associated shift hour (if applicable), and year. security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.READ operationId: getHoliday parameters: - $ref: '#/components/parameters/HolidayId' responses: '200': description: Response for status 200 content: application/json: schema: type: object properties: holidays: type: array items: type: object properties: name: type: string maxLength: 80 description: The Name of the object. date: type: string format: date description: The Date of the object. type: type: string enum: - business_holiday - shift_holiday description: The Type of the object. shift_hour: type: - object - 'null' properties: name: type: string description: The Name of the object. maxLength: 255 id: type: string description: The Id of the object. maxLength: 255 required: - name - id description: The Shift hour of the object. additionalProperties: false id: type: string description: The Id of the object. maxLength: 255 year: type: integer format: int32 description: The Year of the object. required: - name - date - type - shift_hour - id - year description: The Item of the object. additionalProperties: false description: The Holidays of the object. maxItems: 100 info: type: object properties: per_page: type: integer format: int32 description: The Per page of the object. page: type: integer format: int32 description: The Page of the object. count: type: integer format: int32 description: The Count of the object. more_records: type: boolean description: The More records of the object. description: The Info of the object. additionalProperties: false required: - holidays description: The Response body of the object. additionalProperties: false '204': description: Response for status 204 delete: tags: - Holidays summary: Delete a specific holiday description: Permanently deletes a specific holiday identified by its ID. This operation is irreversible. Ensure the holiday ID is valid before deletion to avoid errors. security: - iam-oauth2-schema: - ZohoCRM.settings.business_hours.DELETE operationId: deleteHoliday parameters: - $ref: '#/components/parameters/HolidayId' responses: '200': description: Holiday deleted successfully content: application/json: schema: $ref: '#/components/schemas/HolidaysSuccessResponse' '400': description: Bad request - validation errors content: application/json: schema: type: object properties: code: type: string enum: - INVALID_DATA description: The Code of the object. details: type: object description: The Details of the object. additionalProperties: true message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - error description: The Status of the object. description: The Response body of the object. additionalProperties: false components: parameters: Year: name: year in: query required: false description: Filter holidays by year. Must be a valid 4-digit year value within a reasonable range. schema: type: integer format: int32 minimum: 2000 maximum: 2100 description: The Year of the object. ShiftId: name: shift_id in: query required: false description: Filter holidays by shift hour ID. Required when filtering by shift_holiday type. Must be a valid numeric string identifier. schema: type: string pattern: ^[0-9]+$ minLength: 1 maxLength: 30 description: The Shift id of the object. HolidayId: name: holidayId in: path required: true description: Unique identifier of the holiday. Must be a valid numeric string identifier. schema: type: string pattern: ^[0-9]+$ minLength: 1 maxLength: 30 description: The Holiday id of the object. Type: name: type in: query required: false description: 'Filter holidays by type: business holidays apply to all users, shift holidays apply to specific shifts' schema: type: string enum: - business_holiday - shift_holiday description: The Type of the object. schemas: HolidaysSuccessResponse: type: object properties: holidays: type: array items: type: object properties: code: type: string enum: - SUCCESS description: The Code of the object. details: type: object properties: id: type: string description: The unique identifier of the holiday maxLength: 255 description: The Details of the object. additionalProperties: false message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - success description: The Status of the object. required: - code - details - message - status description: The Item of the object. additionalProperties: false description: The Holidays of the object. maxItems: 100 required: - holidays description: The Holidayssuccessresponse of the object. additionalProperties: false InvalidDataResponse: type: object properties: code: type: string enum: - DUPLICATE_DATA - INVALID_DATA - DEPENDENT_FIELD_MISSING description: The Code of the object. details: type: object description: The Details of the object. additionalProperties: true message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - error description: The Status of the object. description: The Item of the object. additionalProperties: false responses: ForbiddenError: description: Forbidden - insufficient permissions to perform this operation content: application/json: schema: type: object properties: code: type: string enum: - NO_PERMISSION description: The Code of the object. details: type: object description: The Details of the object. additionalProperties: true message: type: string description: The Message of the object. maxLength: 255 status: type: string enum: - error description: The Status of the object. required: - code - message - status description: The Response body of the object. additionalProperties: false securitySchemes: iam-oauth2-schema: type: oauth2 flows: authorizationCode: authorizationUrl: https://accounts.zoho.com/oauth/v2/auth tokenUrl: https://accounts.zoho.com/oauth/v2/token refreshUrl: https://accounts.zoho.com/oauth/v2/token scopes: ZohoCRM.settings.business_hours.UPDATE: Access to ZohoCRM.settings.holidays.UPDATE ZohoCRM.settings.business_hours.CREATE: Access to ZohoCRM.settings.holidays.CREATE ZohoCRM.settings.business_hours.READ: Access to ZohoCRM.settings.holidays.READ ZohoCRM.settings.business_hours.DELETE: Access to ZohoCRM.settings.holidays.DELETE