Clockify Custom fields 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 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
    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
    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
    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.
    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
  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'