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.
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.