Clockify Time Off 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 Time Off API
  version: v1
  x-logo:
    altText: Clockify logo
    url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Time Off
  x-displayName: Time Off
paths:
  /v1/workspaces/{workspaceId}/time-off/policies/{policyId}/requests:
    servers:
    - url: https://api.clockify.me/api
    post:
      operationId: createTimeOffRequest
      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 policy identifier across the system.
        example: 63034cd0cb0fb876a57e93ad
        in: path
        name: policyId
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTimeOffRequestV1Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequestFullV1Dto'
          description: OK
      summary: Create a time off request
      tags:
      - Time Off
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/time-off/policies/{policyId}/requests/{requestId}:
    servers:
    - url: https://api.clockify.me/api
    delete:
      operationId: deleteTimeOffRequest
      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 policy identifier across the system.
        example: 63034cd0cb0fb876a57e93ad
        in: path
        name: policyId
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      - description: Represents a time off request identifier across the system.
        example: 6308850156b7d75ea8fd3fbd
        in: path
        name: requestId
        required: true
        schema:
          type: string
          description: Represents a time off request identifier across the system.
          example: 6308850156b7d75ea8fd3fbd
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequestV1Dto'
          description: OK
      summary: Delete a time off request
      tags:
      - Time Off
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    patch:
      operationId: changeTimeOffRequestStatus
      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 policy identifier across the system.
        example: 63034cd0cb0fb876a57e93ad
        in: path
        name: policyId
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      - description: Represents a time off request identifier across the system.
        example: 6308850156b7d75ea8fd3fbd
        in: path
        name: requestId
        required: true
        schema:
          type: string
          description: Represents a time off request identifier across the system.
          example: 6308850156b7d75ea8fd3fbd
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusTimeOffRequestV1Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequestV1Dto'
          description: OK
      summary: Change a time off request status
      tags:
      - Time Off
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/time-off/policies/{policyId}/users/{userId}/requests:
    servers:
    - url: https://api.clockify.me/api
    post:
      operationId: createTimeOffRequestForOther
      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 policy identifier across the system.
        example: 63034cd0cb0fb876a57e93ad
        in: path
        name: policyId
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      - description: Represents a user identifier across the system.
        example: 60f924bafdaf031696ec6218
        in: path
        name: userId
        required: true
        schema:
          type: string
          description: Represents a user identifier across the system.
          example: 60f924bafdaf031696ec6218
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTimeOffRequestV1Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequestFullV1Dto'
          description: OK
      summary: Create a time off request for a user
      tags:
      - Time Off
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/time-off/requests:
    servers:
    - url: https://api.clockify.me/api
    post:
      operationId: getTimeOffRequest
      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/GetTimeOffRequestsV1Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequestsWithCountV1Dto'
          description: OK
      summary: Get all time off requests on a workspace
      tags:
      - Time Off
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
components:
  schemas:
    StatusTimeOffRequestV1Request:
      type: object
      properties:
        note:
          type: string
          description: Provide the note you would like to use for changing the time off request.
          example: Time Off Request Note
        status:
          type: string
          description: Provide the status you would like to use for changing the time off request.
          example: APPROVED
          enum:
          - APPROVED
          - REJECTED
    GetTimeOffRequestsV1Request:
      type: object
      properties:
        end:
          type: string
          description: Return time off requests created before the specified time in requester's time zone. Provide end in format YYYY-MM-DDTHH:MM:SS.ssssssZ
          format: date-time
          example: '2022-08-26T23:55:06.281873Z'
        page:
          maximum: 1000
          type: integer
          description: Page number.
          format: int32
          example: 1
          default: 1
        pageSize:
          maximum: 200
          minimum: 1
          type: integer
          description: Page size.
          format: int32
          example: 50
          default: 50
        start:
          type: string
          description: Return time off requests created after the specified time in requester's time zone. Provide start in format YYYY-MM-DDTHH:MM:SS.ssssssZ
          format: date-time
          example: '2022-08-26T08:00:06.281873Z'
        statuses:
          uniqueItems: true
          type: array
          description: Filters time off requests by status.
          example:
          - APPROVED
          - PENDING
          items:
            type: string
            description: Filters time off requests by status.
            example: '["APPROVED","PENDING"]'
            enum:
            - PENDING
            - APPROVED
            - REJECTED
            - ALL
        userGroups:
          uniqueItems: true
          type: array
          description: Provide the user group ids of time off requests.
          example:
          - 5b715612b079875110791342
          - 5b715612b079875110791324
          - 5b715612b079875110793142
          items:
            type: string
            description: Provide the user group ids of time off requests.
            example: '["5b715612b079875110791342","5b715612b079875110791324","5b715612b079875110793142"]'
        users:
          uniqueItems: true
          type: array
          description: Provide the user ids of time off requests. If empty, will return time off requests of all users (with a maximum of 5000 users).
          example:
          - 5b715612b079875110791432
          - b715612b079875110791234
          items:
            type: string
            description: Provide the user ids of time off requests. If empty, will return time off requests of all users (with a maximum of 5000 users).
            example: '["5b715612b079875110791432","b715612b079875110791234"]'
    PeriodV1Request:
      type: object
      properties:
        days:
          maximum: 999
          minimum: 1
          type: integer
          description: Provide number of days.
          format: int32
          example: 3
        end:
          type: string
          description: Provide end date in YYYY-MM-DD format.
          example: '2021-12-25'
        start:
          type: string
          description: Provide start date in YYYY-MM-DD format.
          example: '2021-12-23'
      description: Represents period of time off request including start and end date.
    TimeOffRequestPeriodDto:
      type: object
      properties:
        halfDay:
          type: boolean
        halfDayHours:
          $ref: '#/components/schemas/Period'
        halfDayPeriod:
          type: string
        period:
          $ref: '#/components/schemas/Period'
      description: Represents the period the time off request.
    TimeOffRequestPeriodV1Request:
      required:
      - period
      type: object
      properties:
        halfDayPeriod:
          type: string
          description: Represents the half day period.
          example: NOT_DEFINED
          enum:
          - FIRST_HALF
          - SECOND_HALF
          - NOT_DEFINED
        isHalfDay:
          type: boolean
          description: Indicates whether time off is half day.
          example: false
          default: false
        period:
          $ref: '#/components/schemas/PeriodV1Request'
        timeOffHalfDayPeriod:
          type: string
          enum:
          - FIRST_HALF
          - SECOND_HALF
          - NOT_DEFINED
      description: Provide the period you would like to use for creating the time off request. If `timeZone` isn't set, should be aligned with time zone for user in settings. Can be shifted from user time zone with explicit setting of `timeZone`.
    TimeOffRequestV1Dto:
      type: object
      properties:
        balanceDiff:
          type: number
          description: Represents the balance difference
          format: double
          example: 1
        createdAt:
          type: string
          description: Represents the date when time off request is created. Date is in format YYYY-MM-DDTHH:MM:SS.ssssssZ
          format: date-time
          example: '2022-08-26T08:32:01.640708Z'
        id:
          type: string
          description: Represents time off requester identifier across the system.
          example: 5b715612b079875110791111
        note:
          type: string
          description: Represents the note of the time off request.
          example: Time Off Request Note
        policyId:
          type: string
          description: Represents policy identifier across the system.
          example: 5b715612b079875110792333
        status:
          $ref: '#/components/schemas/TimeOffRequestStatus'
        timeOffPeriod:
          $ref: '#/components/schemas/TimeOffRequestPeriodDto'
        userId:
          type: string
          description: Represents user identifier across the system.
          example: 5b715612b079875110794444
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 5b715612b079875110792222
    TimeOffRequestsWithCountV1Dto:
      type: object
      properties:
        count:
          type: integer
          description: Total count of time off requests.
          format: int32
          example: 1
        requests:
          type: array
          items:
            $ref: '#/components/schemas/TimeOffRequestFullV1Dto'
    CreateTimeOffRequestV1Request:
      required:
      - timeOffPeriod
      type: object
      properties:
        note:
          type: string
          description: Provide the note you would like to use for creating the time off request.
          example: Create Time Off Note
        timeOffPeriod:
          $ref: '#/components/schemas/TimeOffRequestPeriodV1Request'
    TimeOffRequestFullV1Dto:
      type: object
      properties:
        balance:
          type: number
          description: Represents the time off balance.
          format: double
          example: 10
        balanceDiff:
          type: number
          description: Represents the balance difference.
          format: double
          example: 1
        createdAt:
          type: string
          description: Represents the date when time off request is created. It is in format YYYY-MM-DDTHH:MM:SS.ssssssZ
          format: date-time
          example: '2022-08-26T08:32:01.640708Z'
        id:
          type: string
          description: Represents time off requester identifier across the system.
          example: 5b715612b079875110791111
        note:
          type: string
          description: Represents the note of the time off request.
          example: Time Off Request Note
        policyId:
          type: string
          description: Represents policy identifier across the system.
          example: 5b715612b079875110792333
        policyName:
          type: string
          description: Represents the policy name of the time off request.
          example: Days
        requesterUserId:
          type: string
          description: Represents requester user's id.
          example: 5b715612b0798751107925555
        requesterUserName:
          type: string
          description: Represents requester user's username.
          example: John
        status:
          $ref: '#/components/schemas/TimeOffRequestStatus'
        timeOffPeriod:
          $ref: '#/components/schemas/TimeOffRequestPeriodDto'
        timeUnit:
          type: string
          description: Represents the time unit of the time off request.
          example: DAYS
          enum:
          - DAYS
          - HOURS
        userEmail:
          type: string
          description: Represents user's email
          example: nicholas@clockify.com
        userId:
          type: string
          description: Represents user identifier across the system.
          example: 5b715612b079875110794444
        userName:
          type: string
          description: Represents user's username.
          example: Nicholas
        userTimeZone:
          type: string
          description: Represents user's time zone
          example: Europe/Budapest
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 5b715612b079875110792222
      description: Represents the array of time off requests.
    TimeOffRequestStatus:
      type: object
      properties:
        changedAt:
          type: string
          format: date-time
        changedByUserId:
          type: string
        changedByUserName:
          type: string
        changedForUserName:
          type: string
        note:
          type: string
        statusType:
          type: string
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          - ALL
      description: Represents the status the time off request.
    Period:
      type: object
      properties:
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
  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'