Custom Fields
You can work with certain types of Custom Fields using the ClickUp API.
👍 Tip Explore the Custom Field Endpoints.
The Custom Field object
Below is an example Custom Field object. This is the information you'll see about each Custom Field when using the Get Accessible Custom Fields endpoint.
{
"id": "5dc86497-098d-4bb0-87d6-cf28e43812e7",
"name": "Text Field",
"type": "text",
"type_config": {},
"date_created": "1577378759142",
"hide_from_guests": false
}
Properties of the Custom Field object
There are four key properties you will use when working with Custom Fields in the ClickUp API.
- id: This is the unique identifier of a Custom Field available on at least one List in your ClickUp Workspace.
- type: Refers to the Custom Field type.
- type_config: Sets the acceptable values for Custom Field types with specific requirements.
- value: The actual data shown on tasks in ClickUp.
👀 Note Free Forever Plans have 60 uses of Custom Fields. Each use of the Set Custom Field Value endpoint counts as 1 use per request. Uses accumulate across a Workspace and do not reset. When you reach the use limit, you won't lose any data, but you won't be able to edit or create new items with that feature.
Custom Field types
Here is a list of the available Custom Field types. Use these values in the type
property.
-
url
: The URL of any website. -
drop_down
: A series of options in a menu. -
labels
: A flexible list of options, similar to Tags. -
email
: A formatted email address. -
phone
: A formatted phone number with country and area codes. -
date
: A custom date and time. -
short_text
: Enter a single line of plain text. -
text
: Enter a paragraph of plain text. -
checkbox
: A true or false checkbox. -
number
: A formatted numeric value. -
currency
: A Money Custom Field. A formatted amount of money in any currency. -
tasks
: Tasks linked together without Relationships. -
users
: A People Custom Field. Pick people and Teams. -
emoji
: A Rating Custom Field. Use emoji to rate items on a numeric scale. -
automatic_progress
: An automatically calculated progress bar. -
manual_progress
: A progress bar that's manually set. -
location
: A formatted address based on Google Maps.
👀 Note Voting Custom Field values are returned as part of the Custom Field array. Voting Custom Field values cannot be set using the API.
The type_config property
The type_config
property determines what options and requirements apply to a Custom Field. Examples are included below.
Drop down
Dropdown options exist in the options
array. The order of items is determined by the array index. A placeholder
value (string) and default
option are available, but are not currently used in ClickUp.
Sorting options include manual
, name_asc
, and name_desc
. The orderindex
property is a unique, sequential number starting at 0
and ending at the length of the array.
{
"name": "My Dropdown Field",
"type": "drop_down",
"type_config": {
"sorting": "manual",
"default": 0,
"placeholder": "Select a value",
"options": [
{
"id": "option_1_id",
"name": "Option 1",
"color": "#FFFFF",
"orderindex": "0"
},
{
"id": "option_2_id",
"name": "Option 2",
"color": "#000000",
"orderindex": "1"
}
]
}
}
Currency (Money)
You must specify a particular currency in the currency_type
property. The default
option is available, but it is not currently used in ClickUp.
{
"name": "My Currency Field",
"type": "currency",
"type_config": {
"precision": 2,
"currency_type": "USD",
"default": 10
}
}
Emoji
The code_point
property must be a valid Unicode emoji code point, usually written like U+1f613
. Omit the U+
and pass only the hex value as a string.
The count
property sets the maximum number of values the rating can hold, with a minimum value of 1
and a maximum of 5
.
{
"name": "My Emoji Rating Field",
"type": "emoji",
"type_config": {
"code_point": "1f613",
"count": 5
}
}
Labels
A flexible list of options, similar to Tags.
Sorting options include manual
, name_asc
, and name_desc
. The orderindex
property is always provided, must be unique, starts at 0
, and ends at Array.length
.
{
"name": "My Label Field",
"type": "labels",
"type_config": {
"sorting": "manual"
"options": [
{
"id": "option_1_id",
"label": "Label 1",
"color": "#123456",
"orderindex": "0"
},
{
"id": "option_2_id",
"label": "Label 2",
"color": "#FFFFFF",
"orderindex": "1"
}
]
}
}
Automatic progress
An automatically calculated progress bar.
{
"name": "Automatic Progress Bar",
"type": "progress",
"type_config": {
"method": "automatic",
"tracking": {
"subtasks": true,
"assigned_comments": true,
"checklists": true
}
}
}
Manual progress
A progress bar that's manually set. Start, end and current are absolute values. ClickUp will display the current value as a percentage of the total.
{
"name": "Manual Progress Bar",
"type": "progress",
"type_config": {
"method": "manual",
"start": 0,
"end": 100,
"current": 50
}
}
Field values
To set a field value on a task, use the Set Custom Field Value endpoint. The following shows how to change specific custom field types.
The request will always require the body { value: ... }
based on the Custom Field Type.
Url
The value must be a string and a valid URL.
{ "value": "https://clickup.com" }
Drop down
The value must be an ID that matches one of the existing options retrieved from type_config
.
{ "value": "option_1_id" }
The value must be a string and a valid email.
{ "value": "lana@clickup.com" }
Phone
The value must be a string and a valid phone number with country code.
{ "value": "+1 123 456 7890" }
Date
The value
must be Unix time in milliseconds. By default, or if you include "time": false
, only the date is displayed in ClickUp.
To display time in the ClickUp UI, include "time": true
.
👀 Note When requesting tasks that include a Date Custom Field (e.g., when using the GET task or other calls), but do not display a time in ClickUp, the API will return a value in Unix time in milliseconds of 4:00 am in the authorized user's timezone.
{
"value": 1565993299379,
"value_options": {
"time": true
}
}
Text
The value must be a string.
{ "value": "Some text" }
Checkbox
The value must be a boolean.
{ "value": true }
Number
The value must be a number.
{ "value": -28 }
Currency
The value must be a number.
{ "value": 80000 }
Tasks
The value must be an object with the following format. The task_ids
in add
will be added to the field, and the task_ids
in rem
will be removed. The user must have access to all tasks in the request.
{
"value": {
"add": ["task_id_1", "task_id_2"],
"rem": ["task_id_3"]
}
}
Users
The value must be an object with the following format. The users in add
will be added to the field, and the users in rem
will be removed.
{
"value": {
"add": ["user_id_1", "user_id_2"],
"rem": ["user_id_3"]
}
}
Filter by users
To filter by users using the Get Filtered Team Tasks endpoint, input each user_id
as an array into the value parameter.
{
"field_id":"bd12538-4cf0-51f3-13h1-a1c0bedae3f7",
"operator":"ANY",
"value":["user_id_1", "user_id_2"]
}
Emoji (Rating)
The value must be an integer that meets the following conditions:
- The value must be greater than or equal to zero, and
-
The
count
property (which is the maximum value possible) must be greater than or equal to thevalue
.
0 <= value <= field.type_config.count.
{
"value": 4
}
Automatic progress
Automatic progress fields cannot be set by user.
Manual progress
The value must be an object with the current value of the progress. For example, if your start
and end
are 10
and 30
, you would pass 20
to set the manual progress bar at 50%.
{
"value": {
"current": 20
}
}
Labels
The value must be an object with the following format. The ID
for each label must come from the field's type_config
. Any labels that currently exist on a task will be overwritten.
{
"value": ["label_1_id", "label_2_id"]
}
Location
You must provide the latitude lat
, longitude lng
, and formatted address per Google Maps Geocoding API.
{
"value": {
"location":{
"lat": -28.016667,
"lng": 153.4
},
"formatted_address": "Gold Coast QLD, Australia"
}
}