[ Upcoming ] Further additions to the API regarding custom task types

English Forum Developers & API Changelog
1

Summary

This release builds upon the previously introduced “custom” resource_subtype for tasks, expanding the API to begin handling custom types and custom type statuses. The updates enable developers to view and modify the custom type and status of tasks, as well as retrieve all custom types for a given project.

The two key fields that are being introduced on the task routes are:

  • custom_type: The custom type associated with the task
  • custom_type_status_option: The status option associated with the task’s custom type

Additionally, a new endpoint has been added to retrieve all custom types for a project: GET /custom_types

Why we’re making this change

The introduction of custom types allows for more granular categorization of tasks, enabling users to better match tasks to their specific use case or workflow. Custom types give tasks a distinct identity based on purpose or functionality, improving task management flexibility.

Who is affected

Developers working with tasks that will now support custom types and custom type statuses. Existing applications will need to account for the new fields (custom_type and custom_type_status_option) when interacting with tasks that have a resource_subtype of "custom".

Timeline

  • This change is effective for users who are in domains in Starter+ tiers
  • Early Q1 2025: GA rollout

Usage

Developers can use the following API endpoints to view & update this new information:

When a task has a resource_subtype of “custom”, two additional fields will be included in the response:

  • custom_type: Contains details about the custom type
  • custom_type_status_option: Contains details about the custom type status option
{
  "data": {
    "name": "{{taskName}}",
    "resource_subtype": "custom",
    "custom_type": {
      "gid": "123",
      "resource_type": "custom_type",
      "name": "bug ticket",
      "enabled": true,
      "custom_type_status_options": [
        {
          "gid": "012",
          "resource_type": "custom_type_status_option",
          "name": "investigating",
          "enabled": true,
          "color": "red",
          "completion_state": "Incomplete"
        },
        {
          "gid": "345",
          "resource_type": "custom_type_status_option",
          "name": "fixed",
          "enabled": true,
          "color": "green",
          "completion_state": "Complete"
        }
      ]
    },
    "custom_type_status_option": {
      "gid": "012",
      "resource_type": "custom_type_status_option",
      "name": "investigating",
      "enabled": true,
      "color": "red",
      "completion_state": "Incomplete"
    }
    // ....
  }
}

For the new route GET /custom_types?project=<project-id>, requests will return an array of custom task type compact resources:

{
  "data": [
    {
      "gid": "123",
      "resource_type": "custom_type",
      "name": "bug ticket",
      "enabled": true,
      "custom_type_status_options": [
        {
          "gid": "012",
          "resource_type": "custom_type_status_option",
          "name": "investigating",
          "enabled": true,
          "color": "red",
          "completion_state": "Incomplete"
        },
        {
          "gid": "345",
          "resource_type": "custom_type_status_option",
          "name": "fixed",
          "enabled": true,
          "color": "green",
          "completion_state": "Complete"
        }
      ]
    }
  ]
}

For the PUT /tasks/{task_gid} endpoint, the update allows you to set or change the custom_type and custom_type_status_option fields for a task. These fields are optional in the request body, but they must adhere to the following rules:

  • The custom_type_status_option must be one of the available options defined for the task’s custom_type, or it must be included in the payload
  • The resource_subtype must be "custom" when updating these fields, either as part of the task or already set for the task
// ...

"custom_type": "123",
"custom_type_status_option": "012",

/// ...

The API validates the input data, ensuring that:

  • resource_subtype must be set to “custom” when these fields are used
  • The custom_type_status_option must be one of the available options in the task’s custom_type

Migration steps

Note that no API feature is being deprecated or removed. However, integrations should still consider the following:

  • New Fields: This release adds new optional fields (custom_type and custom_type_status_option) to the /tasks endpoint. If your application interacts with tasks that have a resource_subtype of “custom”, you will need to handle these new fields
  • Handling resource_subtype: As noted in the previous changelog, applications should ensure they gracefully handle tasks with a resource_subtype of “custom”
  • API Integration: If you have existing integrations with the /tasks endpoint, you should update your integration to support the new custom type and status functionality

Stay tuned

Further details about how custom types might impact other task properties (like completion_state or completed_at) will be provided in future updates. For questions and feedback, feel free to submit them to our team.

3 Likes
2

One thing I would note is that these fields are opt_in fields; you’ll need to use

GET /tasks/{task_gid}?opt_fields=custom_type, custom_type_status_option

to retrieve this info on a task.

1 Like
3

Thanks, @Andrew-asana, for the updates and clear writeup.

In roughly what time frame might the “Stay tuned” updates come? Within days/weeks, or months? I’d trying to decide to wait and address all at once if they might be coming fairly soon.

Thanks,

Larry

1 Like
4

(post deleted by author)