> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.awork.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server.

# Custom Fields

> Custom Fields API Reference.

Custom fields allow users to add custom properties to tasks via projects and project templates. Custom fields can be of different types, such as text, number, date, and more. Custom fields are created at the workspace level, activated for a project and then used at the task level. The field values can then be set and retrieved in the task details.

Custom fields are a great way to store additional information in tasks, such as an external Id, which makes it a lot easier to build API integrations with other tools.

![Custom Fields](/_fern-img/3c17de60ceef64328805eb3a6722ca8f69c66c55a258d2fb178d43ab6ee01727.webp)

## Types of custom fields

The following types are available for custom fields:

| Type            | Description                                          |
| --------------- | ---------------------------------------------------- |
| `text`          | A text input field.                                  |
| `number`        | A number input field.                                |
| `date`          | A date selection.                                    |
| `datetime`      | A date and time selection.                           |
| `select`        | A list of pre-defined selection options.             |
| `coloredSelect` | A list of pre-defined selection options with colors. |
| `link`          | A clickable URL input field.                         |
| `boolean`       | A checkbox.                                          |
| `user`          | A user selection.                                    |

## Creating a custom field

To create a custom field, you need to send a POST request to the custom field definitions endpoint:

**`Create a text custom field`**

```sh title="Create a text custom field"
curl -X POST https://api.awork.com/api/v1/customfielddefinitions \
-H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Service Level",
            "type": "text",
            "entity": "task"
         }'
```

The response contains the `customFieldDefinitionId` which is required for the following requests. See the [API reference](/apiv1/custom-fields/get-custom-field-definitions) for more custom field types.

## Linking a custom field to a project

Next, the custom field must be linked to a project before a value can be set for a task. To do so, you need to send a POST request to the project custom fields endpoint:

**`Link a custom field to a project`**

```sh title="Link a custom field to a project"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/linkcustomfielddefinition \
-H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{
            "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
            "order": 1
         }'
```

Custom fields can be linked to projects and project templates. See the [API reference](/apiv1/custom-fields/post-project-link-custom-field-definition-by-project-id) for more information.

## Setting a custom field value for a task

Finally, you can set a value for the custom field for a task. To do so, you need to send a POST request to the task's  `/setCustomFields` endpoint:

**`Set a custom field value for a task`**

```sh title="Set a custom field value for a task"
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/setcustomfields \
-H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '[
            {
                "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
                "textValue": "S1: Business Critical"
            }
         ]'
```

See the [API reference](/apiv1/custom-fields/post-task-set-custom-fields-by-task-id) for more information.

## Getting the custom field values of a task

To get the values of custom fields of a task, you simply need to fetch the task. The custom field values are included in the response:

**`Get the custom field values of a task`**

```sh title="Get the custom field values of a task"
curl -X GET https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"
```

**`Response`**

```json title="Response"
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "baseType": "projecttask",
    "customFields": [
        {
            "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
            "textValue": "S1: Business Critical"
        }
    ]
    ...
}
```

Learn more about [custom fields](https://support.awork.com/en/articles/custom-fields-53uRWZpHr541).