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.

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.