[ Upcoming ] Introducing placeholders to allocations

English Forum Developers & API Changelog
1

Summary

We’re excited to introduce a new feature to the Asana API: support for placeholders in capacity planning. Placeholders are provisional entries that reserve resources for projects with undefined details. With this enhancement, placeholders—along with domain users—can be allocated to projects.

Please note that, in this release, the ability to create or edit placeholders is available through the Asana web app, but not yet through the API. When API users request allocations, they will receive both allocations assigned to domain users and those assigned to placeholders, though placeholders themselves cannot be directly created or modified via the API at this time.

Why we’re making this change

Our users have expressed a need for placeholders in allocations, and we are responding to that demand. This feature is optional, and you can choose whether to incorporate it into your workflow.

Who is affected

In general, this update will affect developers who currently use the following API endpoints and wish to leverage the new placeholder functionality:

Users of “read” endpoints

Users will now be able to search all allocations belonging to a placeholder (in addition to the existing search by user, project, etc).

For example, with GET /allocations/{allocation_gid}, you’ll currently see something that looks like:

{
  "data": {
    "gid": "12345",
    "resource_type": "allocation",
    ...
    "assignee": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    ...
    "resource_subtype": "project_allocation"
  }
}

Existing responses for allocations assigned to people will remain unchanged. However, allocations assigned to placeholders will look as follows:

{
  "data": {
    "gid": "12345",
    "resource_type": "allocation",
    ...
    "assignee": {
      "gid": "12345",
      "resource_type": "placeholder",
      "name": "RM Engineer 1"
    },
    ...
    "resource_subtype": "project_allocation"
  }
}

If you use the assignee.gid from these API responses for subsequent calls to Asana endpoints that do not yet support placeholders, such requests may be invalid and result in errors. For example, if a user looks up all allocations, then uses GET /users/{user_gid}/teams, to find all teams of a placeholder, the system will reject the request and throw an error.

Users of “write” endpoints

Users can now assign placeholders to allocations by providing a placeholder_id in the request’s assignee field instead of a domain user

Timeline

  • December 2024: Early Access release for select customers
  • July 2025: Broader, gradual rollout to all users

Usage and migration steps

GET https://app.asana.com/api/1.0/allocations/{allocation_gid}

{
  "data": {
    "gid": "12345",
    "resource_type": "allocation",
    ...
    "assignee": {
      "gid": "12345",
      "resource_type": "placeholder",
      "name": "RM Engineer 1"
    },
    ...
    "resource_subtype": "project_allocation"
  }
}

Migration steps

Note that existing behavior will be preserved for all existing allocations. Users will only be affected after they’ve created their first placeholder and allocated it to them.

To integrate the new placeholder functionality smoothly:

  1. Filter placeholder allocations: When using the GET /allocations endpoint, identify allocations where assignee.resource_type is “placeholder” to differentiate them from Domain User allocations.
  2. Adjust API workflow: Ensure your workflow logic excludes or separately handles placeholders, as subsequent API calls using placeholder IDs may not be supported and could result in errors.

As always, before applying changes to your live environment, you may wish to test them in a sandbox to ensure compatibility and prevent disruptions.

By following these steps, you can incorporate the placeholder feature effectively while maintaining your current API workflows.

Questions and Feedback

We’d love to hear your thoughts on this new functionality and its potential use cases. We’re especially curious to know if you would find it valuable to have full CRUD (Create, Read, Update, Delete) support for placeholders via the API.

If this is something you’d be interested in, or if you have suggestions for how this feature could be improved, please let us know! As always, your feedback will help us prioritize future updates.

1 Like
2

Thanks for this introduction !