Clockify Holiday API

openapi: 3.2.0
info:
  description: '## Introduction

    By using this REST API, you can easily integrate Clockify with your own add-ons, push and pull data

    between Clockify and other tools, and create custom add-ons on CAKE.com Marketplace.'
  title: Clockify Holiday API
  version: v1
  x-logo:
    altText: Clockify logo
    url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Holiday
  x-displayName: Holiday
paths:
  /v1/workspaces/{workspaceId}/holidays:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: getHolidays
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 60f91b3ffdaf031696ec61a8
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 60f91b3ffdaf031696ec61a8
      - description: If provided, you'll get a filtered list of holidays assigned to user.
        example: 60f924bafdaf031696ec6218
        in: query
        name: assigned-to
        required: false
        schema:
          type: string
          description: If provided, you'll get a filtered list of holidays assigned to user.
          example: 60f924bafdaf031696ec6218
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HolidayDtoV1'
          description: OK
      summary: Get holidays on a workspace
      tags:
      - Holiday
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    post:
      operationId: createHoliday
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 60f91b3ffdaf031696ec61a8
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 60f91b3ffdaf031696ec61a8
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHolidayRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HolidayDtoV1'
          description: OK
      summary: Create a holiday
      tags:
      - Holiday
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/holidays/in-period:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: getHolidaysInPeriod
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 60f91b3ffdaf031696ec61a8
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 60f91b3ffdaf031696ec61a8
      - description: Filter list of holidays assigned to user.
        example: 60f924bafdaf031696ec6218
        in: query
        name: assigned-to
        required: true
        schema:
          type: string
          description: Filter list of holidays assigned to user.
          example: 60f924bafdaf031696ec6218
      - description: Filter list of holidays starting from start date. Expected date format yyyy-MM-ddThh:mm:ssZ
        example: '2022-12-03T10:59:59.999Z'
        in: query
        name: start
        required: true
        schema:
          type: string
          description: Filter list of holidays starting from start date. Expected date format yyyy-MM-ddThh:mm:ssZ
          example: '2022-12-03T10:59:59.999Z'
      - description: Filter list of holidays ending by end date. Expected date format yyyy-MM-ddThh:mm:ssZ
        example: '2022-12-05T23:59:59.999Z'
        in: query
        name: end
        required: true
        schema:
          type: string
          description: Filter list of holidays ending by end date. Expected date format yyyy-MM-ddThh:mm:ssZ
          example: '2022-12-05T23:59:59.999Z'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HolidayDtoV1'
          description: OK
      summary: Get holidays in a specific period
      tags:
      - Holiday
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/holidays/{holidayId}:
    servers:
    - url: https://api.clockify.me/api
    delete:
      operationId: deleteHoliday
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 60f91b3ffdaf031696ec61a8
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 60f91b3ffdaf031696ec61a8
      - description: Represents a holiday identifier across the system.
        example: 60f927920658241e3cf35e02
        in: path
        name: holidayId
        required: true
        schema:
          type: string
          description: Represents a holiday identifier across the system.
          example: 60f927920658241e3cf35e02
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HolidayDto'
          description: OK
      summary: Delete a holiday
      tags:
      - Holiday
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    put:
      operationId: updateHoliday
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 60f91b3ffdaf031696ec61a8
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 60f91b3ffdaf031696ec61a8
      - description: Represents a holiday identifier across the system.
        example: 60f927920658241e3cf35e02
        in: path
        name: holidayId
        required: true
        schema:
          type: string
          description: Represents a holiday identifier across the system.
          example: 60f927920658241e3cf35e02
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHolidayRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HolidayDtoV1'
          description: OK
      summary: Update a holiday
      tags:
      - Holiday
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
components:
  schemas:
    ContainsUsersFilterRequestForHoliday:
      type: object
      properties:
        contains:
          type: string
          description: Filter type.
          example: CONTAINS
          enum:
          - CONTAINS
          - DOES_NOT_CONTAIN
          - CONTAINS_ONLY
        ids:
          uniqueItems: true
          type: array
          description: Represents a list of filter identifiers.
          example:
          - 5a0ab5acb07987125438b60f
          - 64c777ddd3fcab07cfbb210c
          items:
            type: string
            description: Represents a list of filter identifiers.
            example: '["5a0ab5acb07987125438b60f","64c777ddd3fcab07cfbb210c"]'
        status:
          type: string
          description: Filters entities by status.
          example: ACTIVE
          enum:
          - ALL
          - ACTIVE
          - INACTIVE
        statuses:
          type: array
          items:
            type: string
      description: Provide list with users ids and corresponding status.
    CreateHolidayRequestV1:
      required:
      - datePeriod
      - name
      type: object
      properties:
        automaticTimeEntryCreation:
          $ref: '#/components/schemas/AutomaticTimeEntryCreationRequest'
        color:
          pattern: ^#(?:[0-9a-fA-F]{6}){1}$
          type: string
          description: 'Provide color in format ^#(?:[0-9a-fA-F]{6}){1}$. Explanation: A valid color code should start with ''#'' and consist of six hexadecimal characters, representing a color in hexadecimal format. Color value is in standard RGB hexadecimal format.'
          example: '#8BC34A'
        datePeriod:
          $ref: '#/components/schemas/DatePeriodRequest'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the holiday is shown to new users.
          example: true
          default: false
        name:
          maxLength: 100
          minLength: 2
          type: string
          description: Provide the name of the holiday.
          example: Labour Day
        occursAnnually:
          type: boolean
          description: Indicates whether the holiday occurs annually.
          example: true
          default: false
        userGroups:
          $ref: '#/components/schemas/UserGroupIdsSchema'
        users:
          $ref: '#/components/schemas/UserIdsSchema'
    EntityIdNameDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      description: Contains names of user groups that are assigned to holiday.
    UserGroupIdsSchema:
      type: object
      properties:
        contains:
          type: string
          example: CONTAINS
          enum:
          - CONTAINS
          - DOES_NOT_CONTAIN
        ids:
          uniqueItems: true
          type: array
          description: Represents ids upon which filtering is performed.
          example:
          - 5b715612b079875110791111
          - 5b715612b079875110791222
          items:
            type: string
            description: Represents ids upon which filtering is performed.
            example: '["5b715612b079875110791111","5b715612b079875110791222"]'
        status:
          type: string
          description: Represents user status.
          example: ALL
          enum:
          - ALL
          - ACTIVE
          - INACTIVE
      description: Provide list with user group ids and corresponding status.
    UpdateHolidayRequestV1:
      required:
      - datePeriod
      - name
      - occursAnnually
      type: object
      properties:
        automaticTimeEntryCreation:
          $ref: '#/components/schemas/AutomaticTimeEntryCreationRequest'
        color:
          pattern: ^#(?:[0-9a-fA-F]{6}){1}$
          type: string
          description: 'Provide color in format ^#(?:[0-9a-fA-F]{6}){1}$. Explanation: A valid color code should start with ''#'' and consist of six hexadecimal characters, representing a color in hexadecimal format. Color value is in standard RGB hexadecimal format.'
          example: '#8BC34A'
        datePeriod:
          $ref: '#/components/schemas/DatePeriodRequest'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the holiday is shown to new users.
          example: false
          default: false
        name:
          minLength: 1
          type: string
          description: Provide the name you would like to use for updating the holiday.
          example: New Year's Day
        occursAnnually:
          type: boolean
          description: Indicates whether the holiday occurs annually.
          example: true
          default: false
        userGroups:
          $ref: '#/components/schemas/ContainsUserGroupFilterRequest'
        users:
          $ref: '#/components/schemas/ContainsUsersFilterRequestForHoliday'
    HolidayDto:
      type: object
      properties:
        automaticTimeEntryCreation:
          $ref: '#/components/schemas/AutomaticTimeEntryCreationDto'
        color:
          type: string
          description: 'Provide color in format ^#(?:[0-9a-fA-F]{6}){1}$. Explanation: A valid color code should start with ''#'' and consist of six hexadecimal characters, representing a color in hexadecimal format. Color value is in standard RGB hexadecimal format.'
          example: '#8BC34A'
        datePeriod:
          $ref: '#/components/schemas/DatePeriod'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the holiday is shown to new users.
          example: false
          default: false
        id:
          type: string
          description: Represents holiday identifier across the system.
          example: 5b715612b079875110791111
        name:
          type: string
          description: Represents the name of the holiday.
          example: New Year's Day
        occursAnnually:
          type: boolean
          description: Indicates whether the holiday occurs annually.
          example: true
          default: false
        userGroupIds:
          uniqueItems: true
          type: array
          description: Indicates which user groups are included.
          example:
          - 5b715612b079875110791342
          - 5b715612b079875110791324
          - 5b715612b079875110793142
          items:
            type: string
            description: Indicates which user groups are included.
            example: '["5b715612b079875110791342","5b715612b079875110791324","5b715612b079875110793142"]'
        userGroups:
          type: array
          description: Contains names of user groups that are assigned to holiday.
          items:
            $ref: '#/components/schemas/EntityIdNameDto'
        userIds:
          uniqueItems: true
          type: array
          description: Indicates which users are included.
          example:
          - 5b715612b079875110791432
          - 5b715612b079875110791234
          items:
            type: string
            description: Indicates which users are included.
            example: '["5b715612b079875110791432","5b715612b079875110791234"]'
        users:
          type: array
          description: Contains names of users that are assigned to holiday.
          items:
            $ref: '#/components/schemas/EntityIdNameDto'
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 5b715612b079875110792222
    AutomaticTimeEntryCreationRequest:
      required:
      - defaultEntities
      type: object
      properties:
        defaultEntities:
          $ref: '#/components/schemas/DefaultEntitiesRequest'
        enabled:
          type: boolean
          description: Indicates that automatic time entry creation is enabled.
          default: false
      description: Provides automatic time entry creation settings.
    UserIdsSchema:
      type: object
      properties:
        contains:
          type: string
          example: CONTAINS
          enum:
          - CONTAINS
          - DOES_NOT_CONTAIN
        ids:
          uniqueItems: true
          type: array
          description: Represents ids upon which filtering is performed.
          example:
          - 5b715612b079875110791111
          - 5b715612b079875110791222
          items:
            type: string
            description: Represents ids upon which filtering is performed.
            example: '["5b715612b079875110791111","5b715612b079875110791222"]'
        status:
          type: string
          description: Represents user status.
          example: ALL
          enum:
          - ALL
          - ACTIVE
          - INACTIVE
      description: Provide list with user ids and corresponding status.
    DefaultEntitiesDto:
      type: object
      properties:
        projectId:
          type: string
        taskId:
          type: string
    DefaultEntitiesRequest:
      type: object
      properties:
        projectId:
          type: string
          description: Default project for automatically created time entries
        taskId:
          type: string
          description: Default task for automatically created time entries
      description: Provides information about default project and task for automatically created time entries.
    AutomaticTimeEntryCreationDto:
      type: object
      properties:
        defaultEntities:
          $ref: '#/components/schemas/DefaultEntitiesDto'
        enabled:
          type: boolean
      description: Represents automatic time entry creation settings.
    HolidayDtoV1:
      type: object
      properties:
        automaticTimeEntryCreation:
          type: boolean
          description: Indicates that time entries will be automatically created for this holiday.
          example: false
          default: false
        datePeriod:
          $ref: '#/components/schemas/DatePeriod'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the holiday is shown to new users.
          example: false
          default: false
        id:
          type: string
          description: Represents holiday identifier across the system.
          example: 5b715612b079875110791111
        name:
          type: string
          description: Represents the name of the holiday.
          example: New Year's Day
        occursAnnually:
          type: boolean
          description: Indicates whether the holiday occurs annually.
          example: true
          default: false
        projectId:
          type: string
          description: Represents projectId for automatic time entry creation.
          example: 65b36d3c525e243c48f9150f
        taskId:
          type: string
          description: Represents taskId for automatic time entry creation.
          example: 65b36d46fa3df8607e42d21a
        userGroupIds:
          uniqueItems: true
          type: array
          description: Indicates which user groups are included.
          example:
          - 5b715612b079875110791342
          - 5b715612b079875110791324
          - 5b715612b079875110793142
          items:
            type: string
            description: Indicates which user groups are included.
            example: '["5b715612b079875110791342","5b715612b079875110791324","5b715612b079875110793142"]'
        userIds:
          uniqueItems: true
          type: array
          description: Indicates which users are included.
          example:
          - 5b715612b079875110791432
          - 5b715612b079875110791234
          items:
            type: string
            description: Indicates which users are included.
            example: '["5b715612b079875110791432","5b715612b079875110791234"]'
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 5b715612b079875110792222
    DatePeriod:
      type: object
      properties:
        endDate:
          type: string
          format: date
        startDate:
          type: string
          format: date
      description: Represents startDate and endDate of the holiday. Date is in format yyyy-mm-dd
    DatePeriodRequest:
      required:
      - endDate
      - startDate
      type: object
      properties:
        endDate:
          minLength: 1
          type: string
          description: yyyy-MM-dd format date
          example: '2023-02-16'
        startDate:
          minLength: 1
          type: string
          description: yyyy-MM-dd format date
          example: '2023-02-14'
      description: Provide startDate and endDate for the holiday.
    ContainsUserGroupFilterRequest:
      type: object
      properties:
        contains:
          type: string
          description: Filter type.
          example: CONTAINS
          enum:
          - CONTAINS
          - DOES_NOT_CONTAIN
          - CONTAINS_ONLY
        ids:
          uniqueItems: true
          type: array
          description: Represents a list of filter identifiers.
          example:
          - 5a0ab5acb07987125438b60f
          - 64c777ddd3fcab07cfbb210c
          items:
            type: string
            description: Represents a list of filter identifiers.
            example: '["5a0ab5acb07987125438b60f","64c777ddd3fcab07cfbb210c"]'
        status:
          type: string
          description: Filters entities by status.
          example: ACTIVE
          enum:
          - PENDING
          - ACTIVE
          - DECLINED
          - INACTIVE
          - ALL
      description: Provide list with user group ids and corresponding status.
  securitySchemes:
    AddonKeyAuth:
      in: header
      name: x-addon-token
      type: apiKey
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey
    MarketplaceKeyAuth:
      in: header
      name: x-marketplace-token
      type: apiKey
    ReportAddonKeyAuth:
      in: header
      name: x-addon-token
      type: apiKey
x-tagGroups:
- name: Clockify API
  tags:
  - User
  - Workspace
  - Webhooks
  - Approval
  - Client
  - Custom fields
  - Expense
  - Holiday
  - Invoice
  - Project
  - Task
  - Scheduling
  - Tag
  - Time entry
  - Balance
  - Policy
  - Time Off
  - Group
- name: Clockify Reports API
  tags:
  - Shared Report
  - Team Report
  - Time Entry Report
  - Expense Report
- name: Clockify Audit Log API
  tags:
  - Audit Log Report
- name: Deprecated API
  tags:
  - Template (Deprecated)
  - Scheduling (Deprecated)
  - Workspace (Deprecated)
- name: Experimental API
  tags:
  - Entity changes (Experimental)
- name: Guide
  tags:
  - 'Entity Changes: Use cases'