Developer community

If you have questions about using the API, need help developing your custom app, or just want to meet other Asana developers, you should join our active developer community.

👍

Learn help from other developers

The developer community is a great resource to find answers to technical questions. If your question hasn’t already been answered, post it to the forum and you will likely get a quick reply from either a community member or an Asana engineer (usually within a day).

You can also contact Asana support directly by emailing api-support at asana.com or by asking your Asana account manager.

If you have feedback about our docs or API, you can use the feedback form in the footer of our developer docs. While you may not get a response, know that we read every piece of feedback that’s submitted.


Maintaining your app

Be sure that the email address associated with your custom app is being actively monitored. We use this email address to notify developers about critical issues (e.g., if your app gets banned from the API, major deprecations affecting your app, etc.).

If you are using a PAT to authenticate, you should confirm that the email address associated with the Asana account that generated the PAT is being actively monitored by one or more people.

👍

Join the Asana developer community

We also recommend all developers join the Asana developer forum. This is where we will communicate new API features as well as announce upcoming breaking changes and deprecations.

To ensure you don’t miss these announcements, we encourage you to turn on notifications for the Platform News section of the community.


Troubleshooting issues

If your app is having issues, follow these best practices to help you troubleshoot:

  • Carefully read any error messages (see error codes for more details)
  • Check if an API deprecation or breaking change is causing the issue
  • Check the status of Asana’s services to confirm they’re running and not potentially causing your issues
  • Check the developer forum to see if others are having the same issue. It could be an API bug
    • If you can't find an answer in the community, post your issue and someone will likely help. Please include all of the required information to reproduce the issue (e.g., cURL request with full response). Never post a PAT to the forum (or share it anywhere else).
  • Email Asana support: api-support at asana.com

Additional tips and recommendations

Organizing custom reports and data exports

It is common for customers to use the API to export Asana data. You can use portfolios as a container for the Asana data you want to access with your script/app.

For instance, if you want to export data from certain Asana portfolios and projects, start by creating a new portfolio. Then add all of the projects and portfolios you want to report on to this new portfolio. For reference, here is an overview of how portfolios work in Asana.

Once all of your target data is in this new top-level portfolio, you can create a custom exports script to pull all this data via the API. A high-level approach could be:

  1. Requesting the portfolio items from the top-level portfolio
  2. Collect the GIDs for all of the projects in your portfolio
  3. If the item is another portfolio, request its items until you are down to just a collection of the projects that are nested within your top-level portfolio
  4. For each project, request all of its tasks

Here is a code example for a script that uses this approach to pull data from next portfolios and exports it to a CSV: Github repo for the portfolios export script

Working with portfolios (and other collections of objects)

  • Consider using a recursive function if you want to request the data from within nested objects (e.g. portfolios of portfolios or nested subtasks).
  • Requests will often return compact representations of objects. Use the opt_fields parameter to get the exact data you need.

For example, to get the names, custom fields, and owners for the items in a portfolio, use something like:
GET /portfolios/portfolio_gid/items?opt_fields=name,custom_fields.(name|display_value),owner

Connect your app to the Asana user interface

App components are an advanced feature that allow you to visually connect your custom app to the Asana UI. You can use app components to display customized widgets, forms, and rules to create a custom in-product experience for your users.

🚧

Build defensively

When building your app, do not assume API behavior that isn't explicitly documented. We are continually adding features to the Asana product to meet the needs of our customers. As a consequence, the API needs to change along with the web app so that customers can programmatically access new features.

We do everything possible to avoid breaking changes. However, this isn’t always possible. Developers who build defensively encounter fewer disruptions from these changes.