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

[Andrew-asana]

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:

• GET /tasks
• GET /tasks/{task_gid}
• PUT /tasks/{task_gid}
• GET /custom_types?project=<project_id> (NEW!)

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.

[Phil_Seeman]

@Andrew-asana

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

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.

[lpb]

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

[lpb]

Hoping @Andrew-asana will respond to my prior post.

Thanks,

Larry

[Layfando]

Hi team,

Can you confirm that these updates have been rolled out to GA? The new custom_type and custom_type_status_option fields do not appear in the response of the GET /tasks/{task_gid} endpoint for me.

Using them with the PUT /tasks/{task_gid} endpoint results in a 200 response, and the response from that endpoint does return the custom_type and custom_type_status_option fields, though the update hasn’t gone ahead:

[Phil_Seeman]

Hi @Layfando,

Yes, they’re released and available.

For the GET, you’ll need to ask for them specifically using opt_fields=custom_type,custom_type_status_option

For the PUT, you need to also set resource_subtype=custom

[Jakub_Kozakiewicz]

Hi, I’m not sure if this is possible yet, but is there a way to use custom statuses when creating a new task via the API?
Also, for context, I’m creating the task in a previously created project from a template using an API call.

This is my body:

{
  "data": {
    "name": "Some title",
    "projects": ["XXX"],
    "due_on": "2025-01-01",
    "recurrence": {
      "type": "monthly",
      "data": {
        "date": 1,
        "frequency": 1
      }
    }
  }
}

[Stephen_Li]

@Jakub_Kozakiewicz - I haven’t done any testing of my own yet, but based on the OP and the endpoints listed (only GETs and PUT, while the create task is a POST), I think you might need to create the task without the custom type first, return the new task, and then update that task with the. custom task type and status (see @Phil_Seeman’s post earlier in this thread for more on opting into the new fields in your return payload and setting resource_subtype in your request).

[Jakub_Kozakiewicz]

Thanks for your response. Could you help me with the body? What should it look like if I only want to update the custom status?

Now I have something like this:

{
  "data": {
    "resource_subtype": "custom",
    "custom_type": "Content",
    "custom_type_status_option": "Not started"
  }
}

and it’s not working

[Phil_Seeman]

@Jakub_Kozakiewicz,

Custom types and their status options are objects, each with their own gid. When writing them to the API, you have to send the gid of the object, not text.

[Layfando]

I’m also still having issues using the PUT endpoint successfully, even when resource_subtype, custom_type and custom_type_status_option are all specified.

[Phil_Seeman]

@Layfando did you switch to using gids and not text for the type and status values? If so, please post exactly what you’re sending to Asana.

[John_Vu]

@Layfando, @Phil_Seeman is right. In order to update the custom_type_status_option of a task using the Update a task (PUT /tasks/{task_gid}) endpoint you’ll need to provide the gid of the custom_type_status_option you want your task to be updated to.

You should be able to get the gid of the specific custom_type_status_option that you want to set your task to by making an API call to our new Get all custom types associated with an object (/custom_types) endpoint. NOTE: there is currently a bug with this endpoint where it’s not returning gid of custom_type_status_option properly → here’s the work around: API /custom_types does not return the status option GID - #3 by Phil_Seeman

---

In roughly what time frame might the “Stay tuned” updates come? Within days/weeks, or months?

@lpb → checking with the team. Will update once I am able to get an answer.

[John_Vu]

@lpb got a response about “Stay tuned”, this is looking more like 6+ months time-frame

[lpb]

Great; thank you so much, @John_Vu!