openapi: 3.1.0 info: title: ClickUp Custom Fields API description: >- The ClickUp Custom Fields API allows developers to retrieve available custom fields for a list and set or update custom field values on tasks. Custom fields extend the default task data model with user-defined attributes such as dropdowns, labels, numbers, dates, and relationships. This API is essential for integrations that need to read or write structured metadata beyond the standard task fields. version: '2.0' contact: name: ClickUp Support url: https://help.clickup.com termsOfService: https://clickup.com/terms externalDocs: description: ClickUp Custom Fields API Documentation url: https://developer.clickup.com/reference/get-accessible-custom-fields servers: - url: https://api.clickup.com/api/v2 description: ClickUp API v2 Production Server tags: - name: Custom Fields description: >- Operations for retrieving custom field definitions and setting custom field values on tasks. security: - bearerAuth: [] paths: /list/{list_id}/field: get: operationId: getAccessibleCustomFields summary: Get accessible custom fields description: >- Retrieves all custom fields that are accessible on a specific list. Returns field definitions including type, name, configuration, and possible values for dropdown and label fields. tags: - Custom Fields parameters: - $ref: '#/components/parameters/listId' responses: '200': description: Successfully retrieved custom fields content: application/json: schema: type: object properties: fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinition' '401': description: Unauthorized '404': description: List not found /task/{task_id}/field/{field_id}: post: operationId: setCustomFieldValue summary: Set custom field value description: >- Sets the value of a custom field on a task. The value format depends on the custom field type. For dropdown fields, provide the option order index. For label fields, provide an array of label IDs. For relationship fields, provide an array of task IDs. tags: - Custom Fields parameters: - $ref: '#/components/parameters/taskId' - $ref: '#/components/parameters/fieldId' - name: custom_task_ids in: query description: >- If you want to reference a task by its custom task ID, this value must be true. schema: type: boolean - name: team_id in: query description: >- Required when custom_task_ids is set to true. The Workspace ID. schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: value: description: >- The value to set for the custom field. The type depends on the field type. Strings for text, numbers for numeric, arrays for labels and relationships, integers for dropdowns. required: - value responses: '200': description: Custom field value set successfully '400': description: Bad request - invalid value for field type '401': description: Unauthorized '404': description: Task or field not found delete: operationId: removeCustomFieldValue summary: Remove custom field value description: >- Removes the value of a custom field from a task, resetting it to empty. tags: - Custom Fields parameters: - $ref: '#/components/parameters/taskId' - $ref: '#/components/parameters/fieldId' - name: custom_task_ids in: query description: >- If you want to reference a task by its custom task ID, this value must be true. schema: type: boolean - name: team_id in: query description: >- Required when custom_task_ids is set to true. The Workspace ID. schema: type: integer responses: '200': description: Custom field value removed successfully '401': description: Unauthorized '404': description: Task or field not found components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- ClickUp personal API token or OAuth access token. parameters: listId: name: list_id in: path required: true description: >- The unique identifier of the list. schema: type: integer taskId: name: task_id in: path required: true description: >- The unique identifier of the task. schema: type: string fieldId: name: field_id in: path required: true description: >- The unique identifier of the custom field. schema: type: string schemas: CustomFieldDefinition: type: object description: >- A custom field definition with its configuration and type information. properties: id: type: string description: >- The unique identifier of the custom field. name: type: string description: >- The name of the custom field. type: type: string enum: - url - drop_down - email - phone - date - text - checkbox - number - currency - tasks - users - emoji - label - automatic_progress - manual_progress - short_text - location description: >- The type of the custom field. type_config: type: object description: >- Configuration specific to the field type. Contains options for dropdown and label fields, currency settings, etc. properties: default: type: integer description: >- Default option index for dropdown fields. placeholder: type: string nullable: true description: >- Placeholder text for text fields. new_drop_down: type: boolean description: >- Whether this is a new-style dropdown. options: type: array items: type: object properties: id: type: string description: >- The option ID. name: type: string description: >- The option display name. value: type: string nullable: true description: >- The option value. type: type: string nullable: true description: >- The option type. color: type: string nullable: true description: >- The hex color code of the option. orderindex: type: integer description: >- The order index of the option. label: type: string nullable: true description: >- The label text for the option. description: >- Available options for dropdown and label fields. include_guests: type: boolean description: >- Whether to include guests for user fields. include_team_members: type: boolean description: >- Whether to include team members for user fields. precision: type: integer description: >- Decimal precision for number and currency fields. currency_type: type: string description: >- Currency type code for currency fields (e.g., USD, EUR). date_created: type: string description: >- Unix timestamp when the field was created. hide_from_guests: type: boolean description: >- Whether the field is hidden from guests. required: type: boolean description: >- Whether the field is required on tasks.