Custom Fields

Creating Custom fields are now available with the Teamwork API V3. You can retrieve custom fields from using the task and project Teamwork API V2.

Custom fields allow you to add extra data to your projects and tasks. You can create a field for cost, client name, payment status, or anything else that’s important to help you manage and track your work. This allows you to use Teamwork in whatever way best suits your needs.

You can create custom fields that are specific to a project, or, if you are an administrator on the account, you can add a custom field that can be used across the entire organisation.

Note: Custom fields are available on the per-user Premium subscription plan and above.

The 3 types of custom fields that can be used are:

Project level custom fields
Site wide custom fields for tasks (administrator permissions needed)
Site wide custom fields for projects (administrator permissions needed)

We currently support custom fields of types:

Text - "text-short"
Number - "number-integer"
Dropdown - "dropdown"

To add a custom field to a project or task, you'll need to first create a custom field. Once the custom field is created, it's available to attach to a project or task.

To add a custom field to a project or task, you use the V1 Teamwork API and pass in the custom field object.

To get custom fields associated with tasks and projects, you need to use our V2 of the API. You'll find them here.

Quick Start Guide - adding a custom field to a task

Let's take a quick example to get you started !

I want to add a dropdown to tasks, which we will call "feature". This will help me when creating tasks, I can select what feature the task is associated with. I would like this custom field to be a dropdown, so I will send in type "dropdown". I will use the create custom field endpoint, and pass in:

Once you get back an API response 201, you can then attach this field to your task using the parameter "customFields" along with the value inside the payload:

JSON Request

POST

/projects/api/v3/customfields.json

{
    "customField": {
        "entity": "task",
        "projectId": 462683,
        "name": "Feature for task",
        "description": "These are the option for selection for the feature it's relating to.",
        "type": "dropdown",
        "isPrivate": false,
        "required": false,
        "options": {
            "choices": [
                {
                    "color": "#F1C40F",
                    "value": "Time tracking"
                },
                {
                    "color": "#F39C12",
                    "value": "Logging tasks"
                },
                {
                    "color": "#C0392B",
                    "value": "Invoicing"
                }
            ]
        }
    }
}

Attach this field to a task using the parameter "customFields" along with the value inside the payload

{
"todo-item":{
"use-defaults":false,
"completed":false,
"content":"Adding a dropdown",
"tasklistId":1546931,
"creator-id":0,
"notify":false,
"responsible-party-id":"0",
"start-date":"",
"due-date":"",
"description":"This is a task with a custom field which is a dropdown.",
"priority":"",
"progress":0,
"parentTaskId":0,
"tagIds":"",
"everyone-must-do":false,
"predecessors":[
],
"reminders":null,
"columnId":0,
"commentFollowerIds":"-1",
"changeFollowerIds":"-1",
"grant-access-to":"",
"private":false,
"customFields":[ //null for the values you did not select
{
"customFieldId":200,
"value":"Logging tasks"
}
],
"estimated-minutes":0,
"pendingFileAttachments":[
],
"updateFiles":true,
"attachments":"",
"removeOtherFiles":true,
"attachmentsCategoryIds":"",
"pendingFileAttachmentsCategoryIds":"",
"repeatOptions":{
"selecteddays":"",
"editRecurringOption":"One",
"repeatEndDate":"noEndDate",
"repeatsFreq":"norepeat",
"monthlyRepeatType":"monthDay"
}
}
}

To attach a custom field of type Number to a task, you'll pass in the value along with the ID:

"customFields":[{"customFieldId":199,"value":1}]

To attach a custom field of type Text to a task, you'll pass in the value along with the ID:

"customFields":[{"customFieldId":202,"value":"This is the text"}]

To create custom fields that are accessible across your Teamwork account, you need to have adminstrator permissions. Otherwise, it will return a Forbidden error.

Quick Start Guide - adding a custom field to a project

I want to add a text field to projects, which we will call "Project Client". This will help me when creating projects, I can input what client it is for, this will help later for billing and reporting purposes. I would like this custom field to be a text field, so I will send in type "text-short". I will use the create custom field endpoint, and pass in:

Once you get back an API response 201, you can then attach this field to your project using the parameter “customFields” along with the value inside the payload:

These site level custom fields will not be associated to a project and can be used everywhere!

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.

ertyui

{
"customField":{
"entity":"project",
"name":"Project Client",
"description":"Please use this field to select the client this project will be billed to.",
"type":"text-short",
"isPrivate":false,
"required":false
}
}

201 response

{
   "project":{
      "name":"Project with custom field",
      "description":"",
      "use-tasks":true,
      "use-milestones":true,
      "use-messages":true,
      "use-files":true,
      "use-time":true,
      "use-notebook":true,
      "use-riskregister":false,
      "use-links":true,
      "use-billing":true,
      "use-comments":true,
      "category-id":0,
      "start-date":"",
      "end-date":"",
      "tagIds":"",
      "onboarding":false,
      "templateDateTargetDefault":"start",
      "grant-access-to":"",
      "private":false,
      "customFields":[
         {
            "customFieldId":226,
            "value":"Apple"
         }
      ],
      "people":"232000,272441,273628,274410,284262",
      "projectOwnerId":"0",
      "companyId":107942
   }
}

To add site level custom fields for projects, you need to pass an entity of:

entity: "project"

To add site level custom fields for tasks, you need to pass an entity of:

entity: "task"