Clockify Approval 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 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…
      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:
    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.
    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.
    DateRangeDto:
      type: object
      properties:
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
      description: Represents date range object.
    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'
    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.
    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.
    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
    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.
    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.
    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.
    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.
    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
    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.
    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.
    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.
  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'