openapi: 3.1.0 info: title: Helpcenter Holidays API version: 1.0.0 description: Operations for managing holidays that affect business hours and shift schedules 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: 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. 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. 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: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter