Zoho CRM Holidays API

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: 2

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-holidays-api-openapi.yml