Custom Fields

You can work with certain types of Custom Fields using the ClickUp API.

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.

1. id: This is the unique identifier of a Custom Field available on at least one List in your ClickUp Workspace.
2. type: Refers to the Custom Field type.
3. type_config: Sets the acceptable values for Custom Field types with specific requirements.
4. value: The actual data shown on tasks in ClickUp.

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.

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" }

Email

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.

{ 
"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 the value .

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"
    }
}