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 using 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: This refers to the Custom Field Type.
3. type_config: This property sets the acceptable values for Custom Fields types with specific requirements.
4. value: The value is the actual data shown in ClickUp on tasks.

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

The drop down 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 in use in ClickUp.

{
    "name": "My Drop Down Field",
    "type": "drop_down",
    "type_config": {
        "default": 0,
        "placeholder": "Select a value",
        "options": [
            {
                "id": "UUID",
                "name": "Option 1",
                "color": "#FFFFF"
            },
            {
                "id": "UUID",
                "name": "Option 2",
                "color": "#000000"
            }
        ]
    }
}

Currency (Money)

You must specify a particular currency in the currency_type property. The default option is available, but it is not currently in use 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 value, many times written like U+1f613. Please omit the U+ and only pass the hex value of the code point as a string.

The count property set the maximum number of values the rating can hold. The minimum value is 1 and the maximum is 5.

{
    "name": "My Emoji Rating Field",
    "type": "emoji",
    "type_config": {
        "code_point": "1f613",
        "count": 5
    }
}

Labels

A flexible list of options, similar to Tags.

{
    "name": "My Label Field",
    "type": "labels",
    "type_config": {
        "options": [
            {
                "id": "UUID",
                "label": "Label 1",
                "color": "#123456"
            },
            {
                "id": "UUID",
                "label": "Label 2",
                "color": "#FFFFFF"
            }
        ]
    }
}

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.

{
    "name": "Manual Progress Bar",
    "type": "progress",
    "type_config": {
        "method": "manual",
        "start": 0,
        "end": 100
    }
}

Field values

To set a field value on a task use the Set Custom Field Value endpoint.

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.

For example: { "value": "https://clickup.com" }

Drop down

The value must be a UUID that matches the drop down option that you retrieve from type_config.

For example: { "value": "UUID" }

Email

The value must be a string and a valid email. For example: { "value": "lana@clickup.com" }

Phone

The value must be a string and a valid phone number with country code. For example: { "value": "+1 123 456 7890" }

Date

The value must be Unix time in milliseconds. By default, or if you include "time": false then only the date is displayed in ClickUp.

To display the time in the ClickUp UI, include "time": true as shown in the example below.

{ 
"value": 1565993299379 
    "value_options": {
        "time": true
    }
}

Text

The value must be a string.

For example: { "value": "Some text" }

Checkbox

The value must be a boolean.

For example: { "value": true }

Number

The value must be a number

For example: { "value": -28 }

Currency

The value must be a number.

For example: { "value": 80000 }

Tasks

The value must be an object with the following format. The task_ids in add will get added to the field, and the task_ids in rem will be removed. The user must have access to all of the tasks in the request.

{
    "value": {
        "add": ["wmq3", "qt15"],
        "rem": ["wxm7"]
    }
}

Users

The value must be an object with the following format. The users in add will get added to the field, and the users in rem will be removed.

{
    "value": {
        "add": [184, 193],
        "rem": [183]
    }
}

Filter by users

To filter by users with 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":[123456,765432]
}

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

The value of this Custom Field is automatically calculated for each task. You cannot set an Automation Progress Custom Field in ClickUp or using the API.

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 respectively, you would need to 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 UUID for each label must come from the field's type_config. Any labels that currently exist on a task will be overwritten.

{
    "value": ["UUID_1", "UUID_2"]
}

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