openapi: 3.0.1
info:
  description: "## Introduction\nBy using this REST API, you can easily integrate Clockify with your own add-ons, push and pull data\nbetween Clockify and other tools, and create custom add-ons on [CAKE.com Marketplace](https://marketplace.cake.com).\nWhether you’re looking to automate time tracking, generate custom reports, or build other custom\nintegrations, our API provides the flexibility and power you need to get the job done. If you\nhave any questions or run into any issues while using our API, don’t hesitate to reach out to us for help.\nYou can also post questions on Stack Overflow with the Clockify tag to get help from the community.\n## Authentication\nTo authenticate your requests to your API, make sure to include either the ‘X-Api-Key’ or the\n‘X-Addon-Token’ in the request header, containing your API or Addon key. If your workspace is\non a subdomain (e.g. subdomain.clockify.me), you’ll need to generate a new API key in your\nProfile Settings that will work specifically for that workspace. This ensures that you’re\naccessing data from the correct workspace and helps maintain the security of your data.\n## Webhooks\nWebhooks can enhance your workflow by keeping your add-on up-to-date with the latest changes in\nClockify. With Clockify’s webhooks you can receive real-time notifications when certain events such as\nstarting a timer or deleting a time entry occur in Clockify.\nDepending on the workspace plan, workspace owners and admins can create:\n\n* Up to 3 webhooks on **FREE** plan\n* Up to 10 webhooks per user, with a total of 100 webhooks per entire workspace\non **BASIC**, **STANDARD** and **PRO** plans\n* Up to 100 webhooks per user, with a total of 300 webhooks per entire workspace on **ENTERPRISE** plan\n\n## Rate limiting\nOur REST API has a specific rate limit of 50 requests per second (by addon on one workspace) when\naccessed using X-Addon-Token. Exceeding this limit will result in an error message with the description\n\"Too many requests\".\n## Pagination\nOur REST API supports pagination for all synchronous GET endpoints that retrieve lists of entities.\nWhen an endpoint accepts the `page` and `pageSize` query parameters, it will return a paginated response.\n\nTo control the data returned in a paginated request, you can use the following optional query parameters.\n\n- **page** (integer): The page number you wish to retrieve. This is 1-indexed. If this parameter is omitted,\nthe API will default to the first page (page=1).\n- **pageSize** (integer): The number of items to include on each page. If this parameter is omitted,\na default page size will be used.\n\nEvery response from an endpoint that supports these parameters will include a custom `Last-Page` header.\nThis header provides a simple way to determine if you have reached the end of the data set.\n\n- **true:** The current page is the final page; no more data is available.\n- **false:** Additional pages can be fetched.\n## API URLs\nRefer to the list on what URL to use base on the subdomain and data region settings of your workspace.\n* Global - can be used by workspaces with or without subdomain.\n    * Regular: https://api.clockify.me/api/v1/file/image\n    * Reports: https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed\n* Regional\n    * Non-subdomain\n        * Regular: https://euc1.clockify.me/api/v1/file/image\n        * Reports: https://use2.clockify.me/report/v1/workspaces/{workspaceId}/reports/detailed\n    * Subdomain\n        * Regular: https://euc1.clockify.me/api/v1/file/image\n        * Reports: https://yoursubdomainname.clockify.me/report/v1/workspaces/{workspaceId}/reports/detailed\n* Developer\n    * Regular: https://developer.clockify.me/api/v1/file/image\n    * Reports: https://developer.clockify.me/report/v1/workspaces/{workspaceId}/reports/detailed\n## Regional Server Prefixes\nIf your workspace is in a specific region, you need to change your URL prefix to access v1 API endpoints.\nFor example, this is how **backend** api [v1/file/image](#tag/User/operation/uploadImage) endpoint\nwould look in EU region:\n[https://euc1.clockify.me/api/v1/file/image](https://euc1.clockify.me)\n\nBelow are the available regional server prefixes:\n* **EU (Germany)**: euc1\n* **USA**: use2\n* **UK**: euw2\n* **AU**: apse2\n\n\n## Breaking changes\nBreaking changes in APIs are modifications that disrupt existing integrations,\nrequiring users to update their applications to maintain functionality.\nThese changes can lead to failures or unexpected results if not addressed.\nSee the list of [breaking changes](breaking-changes/).\n\n## Experimental APIs\nThe experimental API has been thoroughly tested and is ready for use in production. However, please note that user feedback may lead to changes in the API’s structure or functionality. If you choose to use the experimental API, be prepared to modify your application code accordingly to accommodate any updates."
  title: Clockify Approval API
  version: v1
  x-logo:
    altText: Clockify logo
    url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Approval
  x-displayName: Approval
paths:
  /v1/workspaces/{workspaceId}/approval-requests:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: getApprovalRequests
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Filters results based on the provided approval state.
        example: PENDING
        in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - PENDING
          - APPROVED
          - WITHDRAWN_APPROVAL
      - description: Represents the column name to be used as sorting criteria.
        example: START
        in: query
        name: sort-column
        required: false
        schema:
          type: string
          enum:
          - ID
          - USER_ID
          - START
          - UPDATED_AT
      - description: Represents the sorting order.
        example: ASCENDING
        in: query
        name: sort-order
        required: false
        schema:
          type: string
          enum:
          - ASCENDING
          - DESCENDING
      - description: Page number.
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
          description: Page number.
          format: int32
          example: 1
          default: 1
      - description: Page size.
        example: 50
        in: query
        name: page-size
        required: false
        schema:
          minimum: 1
          type: integer
          description: Page size.
          format: int32
          example: 50
          default: 50
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApprovalDetailsDtoV1'
          description: OK
      summary: Get approval requests
      tags:
      - Approval
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    post:
      operationId: createApprrovalRequest
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApprovalRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalRequestDtoV1'
          description: Created
      summary: Submit approval request
      tags:
      - Approval
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/approval-requests/resubmit-entries-for-approval:
    servers:
    - url: https://api.clockify.me/api
    post:
      operationId: resubmitApprovalRequest
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApprovalRequest'
        required: true
      responses:
        '200':
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApprovalRequestDtoV1'
          description: OK
      summary: Submit non pending/approved entries/expenses for approval to an existing approval request
      tags:
      - Approval
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/approval-requests/users/{userId}:
    servers:
    - url: https://api.clockify.me/api
    post:
      operationId: createApprovalForOther
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a user identifier across the system.
        example: 5a0ab5acb07987125438b60f
        in: path
        name: userId
        required: true
        schema:
          type: string
          description: Represents a user identifier across the system.
          example: 5a0ab5acb07987125438b60f
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApprovalRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalRequestDtoV1'
          description: Created
      summary: Submit an approval request for a user
      tags:
      - Approval
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/approval-requests/users/{userId}/resubmit-entries-for-approval:
    servers:
    - url: https://api.clockify.me/api
    post:
      operationId: resubmitApprovalRequestForOther
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a user identifier across the system.
        example: 5a0ab5acb07987125438b60f
        in: path
        name: userId
        required: true
        schema:
          type: string
          description: Represents a user identifier across the system.
          example: 5a0ab5acb07987125438b60f
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApprovalRequest'
        required: true
      responses:
        '200':
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApprovalRequestDtoV1'
          description: OK
      summary: Re-submit rejected/withdrawn entries/expenses for an approval of a user
      tags:
      - Approval
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/approval-requests/{approvalRequestId}:
    servers:
    - url: https://api.clockify.me/api
    patch:
      operationId: updateApprovalStatus
      parameters:
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents an approval request identifier across the system.
        example: 940ab5acb07987125438b65y
        in: path
        name: approvalRequestId
        required: true
        schema:
          type: string
          description: Represents an approval request identifier across the system.
          example: 940ab5acb07987125438b65y
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApprovalRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalRequestDtoV1'
          description: OK
      summary: Update an approval request
      tags:
      - Approval
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
components:
  schemas:
    ProjectInfoDto:
      type: object
      properties:
        clientId:
          type: string
          description: Represents client identifier across the system.
          example: 64c777ddd3fcab07cfbb210c
        clientName:
          type: string
          description: Represents client name.
          example: Client X
        color:
          type: string
          description: 'Color 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: '#000000'
        id:
          type: string
          description: Represents project identifier across the system.
          example: 5b641568b07987035750505e
        name:
          type: string
          description: Represents a project name.
          example: Software Development
      description: Represents a project info object.
    RateDto:
      type: object
      properties:
        amount:
          type: integer
          description: Represents an amount as integer.
          format: int32
          example: 10500
        currency:
          type: string
          description: Represents a currency.
          example: USD
      description: Represents cost rate object.
    ApprovalRequestStatusDtoV1:
      type: object
      properties:
        note:
          type: string
          description: Represents an approval requesst note.
          example: This is a sample approval request note.
        state:
          type: string
          description: Represents approval state enum.
          example: APPROVED
          enum:
          - PENDING
          - APPROVED
          - WITHDRAWN_SUBMISSION
          - WITHDRAWN_APPROVAL
          - REJECTED
        updatedAt:
          type: string
          description: Represents a date in yyyy-MM-ddThh:mm:ssZ format.
          format: date-time
          example: '2020-01-01T08:00:00Z'
        updatedBy:
          type: string
          description: Represents user identifier across the system.
          example: 5a0ab5acb07987125438b60f
        updatedByUserName:
          type: string
          description: Represents user name.
          example: juandelacruz
      description: Represents approval request status object.
    ApprovalRequestDtoV1:
      type: object
      properties:
        creator:
          $ref: '#/components/schemas/ApprovalRequestCreatorDtoV1'
        dateRange:
          $ref: '#/components/schemas/DateRangeDto'
        id:
          type: string
          description: Represents approval request identifier across the workspace.
          example: 567687e29ae1f428e7ebf564
        owner:
          $ref: '#/components/schemas/ApprovalRequestOwnerDtoV1'
        status:
          $ref: '#/components/schemas/ApprovalRequestStatusDtoV1'
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      description: Represents a valid approval request data transfer object.
    TagDto:
      type: object
      properties:
        archived:
          type: boolean
          description: Indicates whether tag is archived or not.
          default: false
        id:
          type: string
          description: Represents tag identifier across the system.
          example: 64c777ddd3fcab07cfbb210c
        name:
          type: string
          description: Represents tag name.
          example: Sprint1
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      description: Represents a list of tag objects.
    ApprovalRequestOwnerDtoV1:
      type: object
      properties:
        startOfWeek:
          type: string
          description: Represents a day of the week.
          example: MONDAY
          enum:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
          - SATURDAY
          - SUNDAY
        timeZone:
          type: string
          description: Represents time zone.
          example: Europe/Budapest
        userId:
          type: string
          description: Represents user identifier across the system.
          example: 5a0ab5acb07987125438b60f
        userName:
          type: string
          description: Represents user name.
          example: johndoe
      description: Represents approval request owner object.
    CustomFieldValueDto:
      type: object
      properties:
        customFieldId:
          type: string
          description: Represents custom field identifier across the system.
          example: 44a687e29ae1f428e7ebe305
        sourceType:
          type: string
          description: Represents a custom field value source type.
          example: WORKSPACE
          enum:
          - WORKSPACE
          - PROJECT
          - TIMEENTRY
        timeEntryId:
          type: string
          description: Represents time entry identifier across the system.
          example: 64c777ddd3fcab07cfbb210c
        value:
          type: object
          description: Represents custom field value.
          example: 20231211-12345
      description: Represents a list of custom field value objects.
    UpdateApprovalRequest:
      required:
      - state
      type: object
      properties:
        note:
          type: string
          description: Additional notes for the approval request.
          example: This is a sample note.
        state:
          type: string
          description: Specifies the approval state to set.
          example: PENDING
          enum:
          - PENDING
          - APPROVED
          - WITHDRAWN_SUBMISSION
          - WITHDRAWN_APPROVAL
          - REJECTED
    TimeEntryInfoDto:
      type: object
      properties:
        approvalRequestId:
          type: string
          description: Represents approval identifier across the system.
          example: 5e4117fe8c625f38930d57b7
        billable:
          type: boolean
          description: Indicates whether time entry is billable or not.
          default: false
        costRate:
          $ref: '#/components/schemas/RateDto'
        customFieldValues:
          type: array
          description: Represents a list of custom field value objects.
          items:
            $ref: '#/components/schemas/CustomFieldValueDto'
        description:
          type: string
          description: Represents a time entry description.
          example: This is a sample time entry description.
        hourlyRate:
          $ref: '#/components/schemas/RateDto'
        id:
          type: string
          description: Represents time entry identifier across the system.
          example: 5b715448b0798751107918ab
        isLocked:
          type: boolean
          description: Indicates whether time entry is locked or not.
          default: false
        project:
          $ref: '#/components/schemas/ProjectInfoDto'
        tags:
          type: array
          description: Represents a list of tag objects.
          items:
            $ref: '#/components/schemas/TagDto'
        task:
          $ref: '#/components/schemas/TaskInfoDto'
        timeInterval:
          $ref: '#/components/schemas/TimeIntervalDto'
        type:
          type: string
          description: Represents a time entry type enum.
          example: REGULAR
          enum:
          - REGULAR
          - BREAK
          - HOLIDAY
          - TIME_OFF
      description: Represents a list of time entry info data transfer objects.
    ExpenseCategoryDto:
      type: object
      properties:
        archived:
          type: boolean
          description: Flag that indicates whether the expense category is archived or not.
          default: false
        hasUnitPrice:
          type: boolean
          description: Represents whether expense category has unit price or none.
          default: false
        id:
          type: string
          description: Represents expense category identifier across the system.
          example: 89a687e29ae1f428e7ebe303
        name:
          type: string
          description: Represents expense category name.
          example: Procurement
        priceInCents:
          type: integer
          description: Represents price in cents as integer.
          format: int32
          example: 1000
        unit:
          type: string
          description: Represents expense category unit.
          example: piece
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      description: Represents an expense category object.
    TimeIntervalDto:
      type: object
      properties:
        duration:
          type: string
          description: Represents a time duration.
          example: PT1H30M
        end:
          type: string
          format: date-time
        offsetEnd:
          type: integer
          format: int32
        offsetStart:
          type: integer
          format: int32
        start:
          type: string
          format: date-time
        timeZone:
          type: string
        zonedEnd:
          type: string
          format: date-time
        zonedStart:
          type: string
          format: date-time
      description: Represents a time interval object.
    ExpenseHydratedDto:
      type: object
      properties:
        approvalRequestId:
          type: string
          description: Represents approval request identifier across the system.
          example: 445687e29ae1f428e7ebe893
        approvalStatus:
          type: string
          description: Represents the approval status of the expense
          example: PENDING
          enum:
          - PENDING
          - APPROVED
          - UNSUBMITTED
          - REJECTED
          - WITHDRAWN_APPROVAL
          - WITHDRAWN_SUBMISSION
        billable:
          type: boolean
          description: Indicates whether expense is billable or not.
          default: false
        category:
          $ref: '#/components/schemas/ExpenseCategoryDto'
        currency:
          type: string
          description: Represents a currency.
          example: USD
        date:
          type: string
          description: Represents a date in yyyy-MM-dd format.
          example: '2020-01-01'
        detailedApprovalStatus:
          type: string
          description: Represents a detailed approval status of the expense
          example: PENDING
          enum:
          - PENDING
          - APPROVED
          - UNSUBMITTED
          - REJECTED
          - WITHDRAWN_APPROVAL
          - WITHDRAWN_SUBMISSION
        fileId:
          type: string
          description: Represents file identifier across the system.
          example: 745687e29ae1f428e7ebe890
        fileName:
          type: string
          description: Represents file name.
          example: file_12345.csv
        fileUrl:
          type: string
          description: Represents file URL.
        id:
          type: string
          description: Represents expense identifier across the system.
          example: 64c777ddd3fcab07cfbb210c
        isLocked:
          type: boolean
          writeOnly: true
        locked:
          type: boolean
        notes:
          type: string
          description: Represents notes for an expense.
          example: This is a sample note for this expense.
        project:
          $ref: '#/components/schemas/ProjectInfoDto'
        quantity:
          type: number
          description: Represents expense quantity as double data type.
          format: double
        task:
          $ref: '#/components/schemas/TaskInfoDto'
        total:
          type: number
          description: Represents expense total as double data type.
          format: double
          example: 10500.5
        userId:
          type: string
          description: Represents user identifier across the system.
          example: 89b687e29ae1f428e7ebe912
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      description: Represents a list of expense hydrated data transfer objects.
    CreateApprovalRequest:
      required:
      - periodStart
      type: object
      properties:
        period:
          type: string
          description: Specifies the approval period. It has to match the workspace approval period setting.
          example: MONTHLY
          enum:
          - WEEKLY
          - SEMI_MONTHLY
          - MONTHLY
        periodStart:
          minLength: 1
          type: string
          description: Specifies an approval period start date in yyyy-MM-ddThh:mm:ssZ format.
          example: '2020-01-01T00:00:00.000Z'
    ApprovalDetailsDtoV1:
      type: object
      properties:
        approvalRequest:
          $ref: '#/components/schemas/ApprovalRequestDtoV1'
        approvedTime:
          type: string
          description: Represents a time duration.
          example: PT1H30M
        billableAmount:
          type: number
          format: double
          example: 2500
        billableTime:
          type: string
          description: Represents a time duration.
          example: PT1H30M
        breakTime:
          type: string
          description: Represents a time duration.
          example: PT1H30M
        costAmount:
          type: number
          description: Represents an amount.
          format: double
          example: 5000
        entries:
          type: array
          description: Represents a list of time entry info data transfer objects.
          items:
            $ref: '#/components/schemas/TimeEntryInfoDto'
        expenseTotal:
          type: number
          description: Represents an amount.
          format: double
          example: 7500
        expenses:
          type: array
          description: Represents a list of expense hydrated data transfer objects.
          items:
            $ref: '#/components/schemas/ExpenseHydratedDto'
        pendingTime:
          type: string
          description: Represents a time duration.
          example: PT1H30M
        trackedTime:
          type: string
          description: Represents a time duration.
          example: PT1H30M
    TaskInfoDto:
      type: object
      properties:
        id:
          type: string
          description: Represents task identifier across the system.
          example: 5b715448b0798751107918ab
        name:
          type: string
          description: Represents task name.
          example: Bugfixing
      description: Represents a project info object.
    ApprovalRequestCreatorDtoV1:
      type: object
      properties:
        userEmail:
          type: string
          description: Represents user email.
          example: johhndoe@example.com
        userId:
          type: string
          description: Represents user identifier across the system.
          example: 5a0ab5acb07987125438b60f
        userName:
          type: string
          description: Represents user name.
          example: johhndoe
      description: Represents approval request creator object.
    DateRangeDto:
      type: object
      properties:
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
      description: Represents date range object.
  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'