[ 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!

[Richard_Sather]

Hi @John_Vu , with the release of ‘global’ task types today, can we expect to soon see API support for updating the status value of a task type?
This is the only major blocker I can see to fully adopting them for myself and promoting their usage to customers that I work with.

[Mikhail_Melikhov]

Hi @Richard_Sather , thank you for the input on the new custom task types functionality!

Generally, task type status values are seen to be part of a stable, predefined workflow that shouldn’t require API syncing, in that sense I wouldn’t expect them to be prioritized to get API exposure soon.

If statuses are highly volatile, managing them via custom fields might be a safer option.

Anyhow, developers feedback is welcome and valued, so if you could share your use case through the Asana Developer Feedback form and highlight the value of this proposal, it will ensure the product team directly reviews it.

[Richard_Sather]

Thanks @Mikhail_Melikhov , I was hoping this would get higher priority as we would essentially like to see full API support for task types, essentially to be treated similar to a single-select field, basically.

For your information, below is what I submitted in the form you provided, including a basic use case (there are many others):

We would like the API to be able to PUT (update) the status of a custom task type. Right now we only have GET (Get a custom type)

There are many use cases where the status of a task type could become used as an ‘action’ to trigger 3rd party apps and once that action is done, change the task type status to confirm it has run successfully.

For example, using each task as an Invoice, it could have statuses as ‘Due’, ‘Create Draft’, ‘Ready’, ‘Send’, ‘Sent’. When a users sets to ‘Create Draft’, it could trigger a webhook to Zapier for example, to prepare the draft using various variables from a database, place it into the task description, and once complete, set the status of the task type to ‘Ready’.

Similarly, when a user sets to ‘Send’, Zapier will send the description field as an email (to a vendor for example) and once complete, set the Task type status to ‘Sent’ to confirm it has been executed.

Without a PUT to custom task types, we need to resort to using a single-select field to work in tandem (i.e. Zapier sets the single-select field and we use a native rule in Asana to set the task type status) which is not ideal and clunky.

[Mikhail_Melikhov]

Thanks for your submission @Richard_Sather! Apologies if I’m missing something, but I’m still not clear on how the ability to modify a custom type’s status options helps here. In your example, the statuses (‘Due’, ‘Create Draft’, ‘Ready’, ‘Send’, ‘Sent’) seem predefined and stable across the whole process, so I’m not seeing where API changes would be expected.

To update a task’s custom status after, for example, a Zapier workflow sends an invoice:

PUT /tasks/{task_gid}
{
  "data": {
    "custom_type_status_option": "{status_option_gid_for_SENT_status}"
  }
}

I’ve just verified it works with “global” custom types just as well.

[Richard_Sather]

Hey @Mikhail_Melikhov , thank you for the engagement, much appreciated!

Apologies if not previously clear but I would like the API to be able to set the value of the task type’s status, rather than change any of the status options.

You are right, the status options are predefined, they will not change and do not require the API to change them (at least, not in the use case I provided). Indeed, the request is for the API to change the custom task type option, in my case from ‘Send’ to ‘Sent’ for example.

But I have good news - I fed your code into Zapier’s custom actions (using the Copilot builder cos I’m no developer) and it works! Thanks

( I had tried this a month ago but it was giving errors for some reason - perhaps it’s added now?)

I’ve just wondering why the API documentation does not currently include endpoints for PUT? The only commands I see in the documentation are Get all custom types associated with an object and Get a custom type.