# Custom Fields

View and set Custom Fields on tasks using the ClickUp API.

# Custom Fields

You can work with certain types of <Glossary>Custom Fields</Glossary> using the ClickUp API.

> 👍 Tip
>
> Explore the [Custom Field Endpoints](https://developer.clickup.com/reference/getaccessiblecustomfields).

## 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](https://developer.clickup.com/reference/getaccessiblecustomfields) endpoint.

```json
{
    "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 <Glossary>Custom Fields</Glossary> in the ClickUp API.

1. **id:** This is the unique identifier of a Custom Field available on at least one <Glossary>List</Glossary> in your ClickUp <Glossary>Workspace</Glossary>.
2. **[type](#custom-field-types):** Refers to the Custom Field type.
3. **[type\_config](#the-type_config-property):** Sets the acceptable values for Custom Field types with specific requirements.
4. **[value](#field-values):** The actual data shown on tasks in ClickUp.

<Callout icon="👀" theme="default">
  ### Note

  Free Forever Plans have 60 uses of <Glossary>Custom Fields</Glossary>. Each use of the Set Custom Field Value endpoint counts as 1 use per request. Uses accumulate across a <Glossary>Workspace</Glossary> 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.
</Callout>

## Custom Field types

Here is a list of the available [Custom Field types](https://docs.clickup.com/en/articles/3071474-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.

<Callout icon="👀" theme="default">
  ### Note

  [Voting Custom Field](https://help.clickup.com/hc/en-us/articles/24266511749527-Use-Voting-Custom-Fields) values are returned as part of the Custom Field array. <Glossary>Voting Custom Field</Glossary> values cannot be set using the API.
</Callout>

## 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.\
<Glossary>Sorting</Glossary> 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.

```json
{
    "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.

```json
{
    "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`.

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

### Labels

A flexible list of options, similar to Tags.

<Glossary>Sorting</Glossary> 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`.

```json
{
    "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.

```json
{
    "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.

```json
{
    "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](https://developer.clickup.com/reference/setcustomfieldvalue). The following shows how to change specific custom field types.

The request will always require the body `{ value: ... }` based on the [Custom Field Type](#custom-field-types).

### Url

The value must be a string and a valid URL.

```json
{ "value": "https://clickup.com" }
```

### Drop down

The value must be an ID that matches one of the existing options retrieved from [`type_config`](#drop-down).

```json
{ "value": "option_1_id" }
```

### Email

The value must be a string and a valid email.

```json
{ "value": "lana@clickup.com" }
```

### Phone

The value must be a string and a valid phone number with country code.

```json
{ "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`.

<Callout icon="👀" theme="default">
  ### Note

  When requesting tasks that include a <Glossary>Date Custom Field</Glossary> (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.
</Callout>

```json
{ 
"value": 1565993299379,
"value_options": {
    "time": true
}
}
```

### Text

The value must be a string.

```json
{ "value": "Some text" }
```

### Checkbox

The value must be a boolean.

```json
{ "value": true }
```

### Number

The value must be a number.

```json
{ "value": -28 }
```

### Currency

The value must be a number.

```json
{ "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.

```json
{
    "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.

```json
{
    "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](https://developer.clickup.com/reference/getfilteredteamtasks) endpoint, input each `user_id` as an array into the value parameter.

```json
{
   "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.`

```json
{
    "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%.

```json
{
    "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`](#labels). Any labels that currently exist on a task will be overwritten.

```json
{
    "value": ["label_1_id", "label_2_id"]
}
```

### Location

You must provide the latitude `lat`, longitude `lng`, and formatted address per [Google Maps Geocoding API](https://developers.google.com/maps/documentation/geocoding/overview).

```json
{
    "value": {
        "location":{
            "lat": -28.016667,
            "lng": 153.4
            },
        "formatted_address": "Gold Coast QLD, Australia"
    }
}
```