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 Custom fields API
  version: v1
  x-logo:
    altText: Clockify logo
    url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Custom fields
  x-displayName: Custom fields
paths:
  /v1/workspaces/{workspaceId}/custom-fields:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: ofWorkspace
      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: If provided, you'll get a filtered list of custom fields that contain the provided string in their name.
        example: location
        in: query
        name: name
        required: false
        schema:
          type: string
          description: If provided, you'll get a filtered list of custom fields that contain the provided string in their name.
          example: location
      - description: If provided, you'll get a filtered list of custom fields that matches the provided string with the custom field status.
        example: VISIBLE
        in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - INACTIVE
          - VISIBLE
          - INVISIBLE
      - description: If provided, you'll get a filtered list of custom fields that matches the provided string with the custom field entity type.
        example:
        - TIMEENTRY
        - USER
        in: query
        name: entity-type
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFieldDtoV1'
          description: OK
      summary: Get custom fields on a workspace
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    post:
      operationId: create
      parameters:
      - description: Represents workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldRequestV1'
        required: true
      responses:
        '201':
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CustomFieldDtoV1'
          description: Created
      summary: Create custom fields on a workspace
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/custom-fields/{customFieldId}:
    servers:
    - url: https://api.clockify.me/api
    delete:
      operationId: delete
      parameters:
      - description: Represents workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents custom field identifier across the system.
        example: 26a687e29ae1f428e7ebe101
        in: path
        name: customFieldId
        required: true
        schema:
          type: string
          description: Represents custom field identifier across the system.
          example: 26a687e29ae1f428e7ebe101
      responses:
        '204':
          description: No Content
      summary: Delete a custom field
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    put:
      operationId: editCustomField
      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 custom field identifier across the system.
        example: 26a687e29ae1f428e7ebe101
        in: path
        name: customFieldId
        required: true
        schema:
          type: string
          description: Represents a custom field identifier across the system.
          example: 26a687e29ae1f428e7ebe101
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomFieldRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDtoV1'
          description: OK
      summary: Update custom field on workspace
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/projects/{projectId}/custom-fields:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: getCustomFieldsOfProject
      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 project identifier across the system.
        example: 5b641568b07987035750505e
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 5b641568b07987035750505e
      - description: If provided, you'll get a filtered list of custom fields that matches the provided string with the custom field status.
        example: INACTIVE
        in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - INACTIVE
          - VISIBLE
          - INVISIBLE
      - description: If provided, you'll get a filtered list of custom fields that matches the provided string with the custom field entity type.
        example: TIMEENTRY
        in: query
        name: entity-type
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFieldDtoV1'
          description: OK
      summary: Get custom fields on a project
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/projects/{projectId}/custom-fields/{customFieldId}:
    servers:
    - url: https://api.clockify.me/api
    delete:
      operationId: removeDefaultValueOfProject
      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 project identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a custom field identifier across the system.
        example: 26a687e29ae1f428e7ebe101
        in: path
        name: customFieldId
        required: true
        schema:
          type: string
          description: Represents a custom field identifier across the system.
          example: 26a687e29ae1f428e7ebe101
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDtoV1'
          description: OK
      summary: Remove custom field from a project
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    patch:
      operationId: editProjectCustomFieldDefaultValue
      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 project identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a custom field identifier across the system.
        example: 26a687e29ae1f428e7ebe101
        in: path
        name: customFieldId
        required: true
        schema:
          type: string
          description: Represents a custom field identifier across the system.
          example: 26a687e29ae1f428e7ebe101
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldProjectDefaultValuesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDtoV1'
          description: OK
      summary: Update custom field on a project
      tags:
      - Custom fields
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
components:
  schemas:
    CustomFieldDtoV1:
      type: object
      properties:
        allowedValues:
          type: array
          description: Represents a list of custom field's allowed values.
          example:
          - New York
          - London
          - Manila
          - Sydney
          - Belgrade
          items:
            type: string
            description: Represents a list of custom field's allowed values.
            example: '["New York","London","Manila","Sydney","Belgrade"]'
        description:
          type: string
          description: Represents custom field description.
          example: This field contains a location.
        entityType:
          type: string
          description: Represents custom field entity type
          example: USER
        id:
          type: string
          description: Represents custom field identifier across the system.
          example: 44a687e29ae1f428e7ebe305
        name:
          type: string
          description: Represents custom field name.
          example: location
        onlyAdminCanEdit:
          type: boolean
          description: Flag to set whether custom field is modifiable only by admin users.
          default: false
        placeholder:
          type: string
          description: Represents custom field placeholder value.
          example: Location
        projectDefaultValues:
          type: array
          description: Represents a list of custom field default values data transfer objects.
          items:
            $ref: '#/components/schemas/CustomFieldDefaultValuesDtoV1'
        required:
          type: boolean
          description: Flag to set whether custom field is mandatory or not.
          default: false
        status:
          type: string
          description: Represents custom field status
          example: VISIBLE
        type:
          type: string
          description: Represents custom field type.
          example: DROPDOWN_MULTIPLE
        workspaceDefaultValue:
          type: object
          description: Represents a custom field's default value in the workspace.
          example: Manila
        workspaceId:
          type: string
          description: Represents workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
    UpdateCustomFieldRequestV1:
      required:
      - name
      - type
      type: object
      properties:
        allowedValues:
          type: array
          description: Represents a list of custom field's allowed values.
          example:
          - New York
          - London
          - Manila
          - Sydney
          - Belgrade
          items:
            type: string
            description: Represents a list of custom field's allowed values.
            example: '["New York","London","Manila","Sydney","Belgrade"]'
        description:
          type: string
          description: Represents a custom field description.
          example: This field contains a location.
        name:
          maxLength: 250
          minLength: 2
          type: string
          description: Represents a custom field name.
          example: location
        onlyAdminCanEdit:
          type: boolean
          description: Flag to set whether custom field is modifiable only by admin users.
          default: false
        placeholder:
          type: string
          description: Represents a custom field placeholder value.
          example: This is a sample placeholder.
        required:
          type: boolean
          description: Flag to set whether custom field is mandatory or not.
          default: false
        status:
          type: string
          description: Represents a custom field status
          example: VISIBLE
          enum:
          - INACTIVE
          - VISIBLE
          - INVISIBLE
        type:
          type: string
          description: Represents a custom field type.
          example: DROPDOWN_MULTIPLE
          enum:
          - TXT
          - NUMBER
          - DROPDOWN_SINGLE
          - DROPDOWN_MULTIPLE
          - CHECKBOX
          - LINK
        workspaceDefaultValue:
          type: object
          description: Represents a custom field's default value in the workspace.
          example: Manila
    CustomFieldRequestV1:
      required:
      - name
      - type
      type: object
      properties:
        allowedValues:
          type: array
          description: Represents a list of custom field's allowed values.
          example:
          - New York
          - London
          - Manila
          - Sydney
          - Belgrade
          items:
            type: string
            description: Represents a list of custom field's allowed values.
            example: '["New York","London","Manila","Sydney","Belgrade"]'
        description:
          type: string
          description: Represents custom field description.
          example: This field contains a location.
        entityType:
          type: string
          description: Represents custom field entity type
          example: TIMEENTRY
          enum:
          - TIMEENTRY
          - USER
        name:
          type: string
          description: Represents custom field name.
          example: location
        onlyAdminCanEdit:
          type: boolean
          description: Flag to set whether custom field is modifiable only by admin users.
          default: false
        placeholder:
          type: string
          description: Represents custom field placeholder value.
          example: Location
        status:
          type: string
          description: Represents custom field status
          example: VISIBLE
          enum:
          - INACTIVE
          - VISIBLE
          - INVISIBLE
        type:
          type: string
          description: Represents custom field type.
          example: DROPDOWN_MULTIPLE
          enum:
          - TXT
          - NUMBER
          - DROPDOWN_SINGLE
          - DROPDOWN_MULTIPLE
          - CHECKBOX
          - LINK
        workspaceDefaultValue:
          type: object
          description: Represents a custom field's default value in the workspace.<li>if type = NUMBER, then value must be a number</li><li>if type = DROPDOWN_MULTIPLE, value must be a list</li><li>if type = CHECKBOX, value must be true/false</li><li>otherwise any string</li>
          example: Manila
    CustomFieldDefaultValuesDtoV1:
      type: object
      properties:
        projectId:
          type: string
          description: Represents project identifier across the system.
          example: 5b641568b07987035750505e
        status:
          type: string
          description: Represents custom field status
          example: VISIBLE
        value:
          type: object
          description: Represents a custom field's default value
          example: Manila
      description: Represents a list of custom field default values data transfer objects.
    CustomFieldProjectDefaultValuesRequest:
      type: object
      properties:
        defaultValue:
          type: object
          description: Represents a custom field's default value.
          example: Manila
        status:
          type: string
          description: Represents a custom field status.
          example: VISIBLE
          enum:
          - INACTIVE
          - VISIBLE
          - INVISIBLE
  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'