Custom Fields

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.

Types of custom fields

The following types are available for custom fields:

Creating a custom field

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

1
curl -X POST https://api.awork.com/api/v1/customfielddefinitions \
2
     -H "Content-Type: application/json" \
3
     -d '{
4
            "name": "Service Level",
5
            "type": "text",
6
            "entity": "task"
7
         }'

The response contains the customFieldDefinitionId which is required for the following requests. See the API reference 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:

1
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/linkcustomfielddefinition \
2
     -H "Content-Type: application/json" \
3
     -d '{
4
            "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
5
            "order": 1
6
         }'

Custom fields can be linked to projects and project templates. See the API reference 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:

1
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/setcustomfields \
2
     -H "Content-Type: application/json" \
3
     -d '[
4
            {
5
                "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
6
                "textValue": "S1: Business Critical"
7
            }
8
         ]'

See the API reference 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:

1
curl -X GET https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000 \
2
     -H "Content-Type: application/json"

1
{
2
    "id": "123e4567-e89b-12d3-a456-426614174000",
3
    "baseType": "projecttask",
4
    "customFields": [
5
        {
6
            "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
7
            "textValue": "S1: Business Critical"
8
        }
9
    ]
10
    ...
11
}

Learn more about custom fields.