Clockify Policy 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 Policy API
  version: v1
  x-logo:
    altText: Clockify logo
    url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Policy
  x-displayName: Policy
paths:
  /v1/workspaces/{workspaceId}/time-off/policies:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: findPoliciesForWorkspace
      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: Page number.
        in: query
        name: page
        required: false
        schema:
          maximum: 1000
          type: string
      - description: Page size.
        example: 50
        in: query
        name: page-size
        required: false
        schema:
          maximum: 200
          minimum: 1
          type: integer
          description: Page size.
          format: int32
          example: 50
          default: 50
      - description: If provided, you'll get a filtered list of policies that contain the provided string in their name.
        example: Holidays
        in: query
        name: name
        required: false
        schema:
          type: string
          description: If provided, you'll get a filtered list of policies that contain the provided string in their name.
          example: Holidays
      - description: If provided, you'll get a filtered list of policies with the corresponding status.
        example: ACTIVE
        in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - ACTIVE
          - ARCHIVED
          - ALL
      - in: query
        name: sort-column
        required: false
        schema:
          type: string
          default: DEFAULT_SORT
      - in: query
        name: sort-order
        required: false
        schema:
          type: string
          default: ASCENDING
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PolicyDtoV1'
          description: OK
      summary: Get policies on a workspace
      tags:
      - Policy
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    post:
      operationId: createPolicy
      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/CreatePolicyRequestV1'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDtoV1'
          description: Created
      summary: Create a time off policy
      tags:
      - Policy
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/time-off/policies/{id}:
    servers:
    - url: https://api.clockify.me/api
    delete:
      operationId: deletePolicy
      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: id
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      responses:
        '200':
          description: OK
      summary: Delete a policy
      tags:
      - Policy
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    get:
      operationId: getPolicy
      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: id
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDtoV1'
          description: OK
      summary: Get a time off policy
      tags:
      - Policy
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    patch:
      operationId: updatePolicyStatus
      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: id
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePolicyStatusRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDtoV1'
          description: OK
      summary: Change a policy status
      tags:
      - Policy
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    put:
      operationId: updatePolicy
      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: id
        required: true
        schema:
          type: string
          description: Represents a policy identifier across the system.
          example: 63034cd0cb0fb876a57e93ad
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePolicyRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDtoV1'
          description: OK
      summary: Update a policy
      tags:
      - Policy
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
components:
  schemas:
    PolicyDtoV1:
      type: object
      properties:
        allowHalfDay:
          type: boolean
          description: Indicates whether the half day is allowed.
          example: false
          default: false
        allowNegativeBalance:
          type: boolean
          description: Indicates whether the negative balance is allowed.
          example: true
          default: false
        approve:
          $ref: '#/components/schemas/PolicyApprovalDto'
        archived:
          type: boolean
          description: Indicates whether the policy is archived.
          example: true
          default: false
        automaticAccrual:
          $ref: '#/components/schemas/AutomaticAccrualDto'
        automaticTimeEntryCreation:
          $ref: '#/components/schemas/AutomaticTimeEntryCreationDto'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the policy is applied to future new users.
          example: false
          default: false
        id:
          type: string
          description: Represents policy identifier across the system.
          example: 5b715612b079875110791111
        name:
          type: string
          description: Represents the name of the policy.
          example: Days
        negativeBalance:
          $ref: '#/components/schemas/NegativeBalanceDto'
        projectId:
          type: string
          description: Represents project identifier across the system.
        timeUnit:
          type: string
          description: Represents the time unit of the policy.
          example: DAYS
          enum:
          - DAYS
          - HOURS
        userGroupIds:
          uniqueItems: true
          type: array
          description: Represents user groups' identifiers across the system. Indicates which user groups are included in the policy.
          example:
          - 5b715612b079875110791342
          - 5b715612b079875110791324
          - 5b715612b079875110793142
          items:
            type: string
            description: Represents user groups' identifiers across the system. Indicates which user groups are included in the policy.
            example: '["5b715612b079875110791342","5b715612b079875110791324","5b715612b079875110793142"]'
        userIds:
          uniqueItems: true
          type: array
          description: Represents users' identifiers across the system. Indicates which users are included in the policy.
          example:
          - 5b715612b079875110791432
          - 5b715612b079875110791234
          items:
            type: string
            description: Represents users' identifiers across the system. Indicates which users are included in the policy.
            example: '["5b715612b079875110791432","5b715612b079875110791234"]'
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 5b715612b079875110792222
    AutomaticAccrualDto:
      type: object
      properties:
        amount:
          type: number
          description: Represents automatic accrual's amount
          format: double
          example: 20
        period:
          type: string
          description: Represents automatic accrual's period
          example: YEAR
          enum:
          - MONTH
          - YEAR
        timeUnit:
          type: string
          description: Represents automatic accrual's time unit
          example: DAYS
          enum:
          - DAYS
          - HOURS
      description: Represents automatic approval settings.
    NegativeBalanceRequest:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 0
          type: number
          description: Represents negative balance amount.
          format: double
          example: 2
        amountValidForTimeUnit:
          type: boolean
        period:
          type: string
          description: Represents negative balance period.
          example: MONTH
          enum:
          - MONTH
          - YEAR
        shouldReset:
          type: boolean
          description: Indicates whether negative balance should be reset at the end of the negative balance period.
          example: true
          default: false
        timeUnit:
          type: string
          description: Represents negative balance time unit.
          example: DAYS
          enum:
          - DAYS
          - HOURS
      description: Provide the negative balance data you would like to use for updating the policy.
    UpdatePolicyRequestV1:
      required:
      - allowHalfDay
      - allowNegativeBalance
      - approve
      - archived
      - everyoneIncludingNew
      - hasExpiration
      - name
      - userGroups
      - users
      type: object
      properties:
        allowHalfDay:
          type: boolean
          description: Indicates whether policy allows half day.
          example: true
          default: false
        allowNegativeBalance:
          type: boolean
          description: Indicates whether policy allows negative balance.
          example: false
          default: false
        approve:
          $ref: '#/components/schemas/PolicyApprovalDto'
        archived:
          type: boolean
          description: Indicates whether policy is archived.
          example: false
          default: false
        automaticAccrual:
          $ref: '#/components/schemas/AutomaticAccrualRequest'
        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'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the policy is shown to new users.
          example: false
          default: false
        hasExpiration:
          type: boolean
          description: Indicates whether the policy has expiration.
          example: false
          default: false
        icon:
          type: string
          description: Provide icon.
          example: UMBRELLA
          enum:
          - UMBRELLA
          - SNOWFLAKE
          - FAMILY
          - PLANE
          - STETHOSCOPE
          - HEALTH_METRICS
          - CHILDCARE
          - LUGGAGE
          - MONETIZATION
          - CALENDAR
        name:
          maxLength: 100
          minLength: 2
          type: string
          description: Provide the name you would like to use for updating the policy.
          example: Days
        negativeBalance:
          $ref: '#/components/schemas/NegativeBalanceRequest'
        userGroups:
          $ref: '#/components/schemas/UserGroupIdsSchema'
        users:
          $ref: '#/components/schemas/UserIdsSchema'
    PolicyApprovalDto:
      type: object
      properties:
        requiresApproval:
          type: boolean
          description: Indicates whether it requires approval
          example: true
          default: false
        specificMembers:
          type: boolean
          description: Indicates whether it requires specific members
          example: false
          default: false
        teamManagers:
          type: boolean
          description: Indicates whether it requires team manager's approval
          example: false
          default: false
        userIds:
          uniqueItems: true
          type: array
          description: Represents set of user's identifier across the system
          example:
          - 6579d126c2fe3b25f20ea001
          - 6579d126c2fe3b25f20ea002
          items:
            type: string
            description: Represents set of user's identifier across the system
            example: '["6579d126c2fe3b25f20ea001","6579d126c2fe3b25f20ea002"]'
      description: Represents approval settings.
    CreatePolicyRequestV1:
      required:
      - approve
      - name
      type: object
      properties:
        allowHalfDay:
          type: boolean
          description: Indicates whether policy allows half days.
          example: false
          default: false
        allowNegativeBalance:
          type: boolean
          description: Indicates whether policy allows negative balances.
          example: true
          default: false
        approve:
          $ref: '#/components/schemas/PolicyApprovalDto'
        archived:
          type: boolean
          description: Indicates whether policy is archived.
          example: true
          default: false
        automaticAccrual:
          $ref: '#/components/schemas/AutomaticAccrualRequest'
        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'
        everyoneIncludingNew:
          type: boolean
          description: Indicates whether the policy is to be applied to future new users.
          example: false
          default: false
        hasExpiration:
          type: boolean
          description: Indicates whether the policy balance should have expiration
          example: false
          default: false
        icon:
          type: string
          description: Provide icon.
          example: UMBRELLA
          enum:
          - UMBRELLA
          - SNOWFLAKE
          - FAMILY
          - PLANE
          - STETHOSCOPE
          - HEALTH_METRICS
          - CHILDCARE
          - LUGGAGE
          - MONETIZATION
          - CALENDAR
        name:
          maxLength: 100
          minLength: 2
          type: string
          description: Represents a name of new policy.
          example: Mental health days
        negativeBalance:
          $ref: '#/components/schemas/NegativeBalanceRequest'
        timeUnit:
          type: string
          description: 'Indicates time unit of the policy. '
          example: DAYS
          enum:
          - DAYS
          - HOURS
        userGroups:
          $ref: '#/components/schemas/UserGroupIdsSchema'
        users:
          $ref: '#/components/schemas/UserIdsSchema'
    ChangePolicyStatusRequestV1:
      required:
      - status
      type: object
      properties:
        status:
          type: string
          description: Provide the status you would like to use for changing the policy.
          example: ACTIVE
          enum:
          - ACTIVE
          - ARCHIVED
          - ALL
    AutomaticAccrualRequest:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 0
          type: number
          description: Represents amount of automatic accrual.
          format: double
          example: 2
        period:
          type: string
          description: Represents automatic accrual period.
          example: MONTH
          enum:
          - MONTH
          - YEAR
        timeUnit:
          type: string
          description: Represents automatic accrual time unit.
          example: DAYS
          enum:
          - DAYS
          - HOURS
      description: Provide automatic accrual settings.
    AutomaticTimeEntryCreationDto:
      type: object
      properties:
        defaultEntities:
          $ref: '#/components/schemas/DefaultEntitiesDto'
        enabled:
          type: boolean
      description: Represents automatic time entry creation settings.
    NegativeBalanceDto:
      type: object
      properties:
        amount:
          type: number
          format: double
        period:
          type: string
        shouldReset:
          type: boolean
        timeUnit:
          type: string
      description: Represents the data about negative balance including amount, time unit and period.
    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.
    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.
    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.
    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
  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'