[New] API CRUD endpoints for allocations

English Forum Developers & API Changelog
1

Summary

Asana recently released Capacity Planning, which allows users to visualize a project’s staffing over time by allocating resources to projects. You can now create, read, update, and delete allocations using the /allocations API!

With the release of these endpoints, developers can integrate Asana capacity planning with other tools and workflows to get the most from the feature. For example:

  • Use GET multiple allocations to create complex reports or surface capacity information in your other internal systems.
  • Use the existing Batch API and POST /allocations to create allocations in bulk.

Usage

Capacity planning is an Enterprise and Enterprise+ tier feature.

Here’s an example to create an allocation:

curl --request POST \ 
--url https://app.asana.com/api/1.0/allocations \ 
--header 'accept: application/json' \ 
--header 'authorization: Bearer XXXXXXXX' \ 
--header 'content-type: application/json' \ 
--data '{ "data": { "parent": "1206741763479744", "assignee": "1205611053350799","start_date": "2024-03-18", "end_date": "2024-04-01", "effort": { "type": "percent", "value": 50}}}'

Response:

{
  "data": {
    "gid": "1206932836428797",
    "resource_type": "allocation",
    "resource_subtype": "project_allocation",
    "end_date": "2024-04-01",
    "start_date": "2024-03-18",
    "parent": {
      "gid": "1206741863479744",
      "resource_type": "project",
      "name": "Example Project"
    },
    "effort": {
      "type": "percent",
      "value": 50
    },
    "assignee": {
      "gid": "1205611053550793",
      "resource_type": "user",
      "name": "John Smith"
    },
    "created_by": {
      "gid": "1202912859352321",
      "resource_type": "user",
      "name": "Anna Faliero"
    }
  }
}

Here’s an example request for reading the above allocation:

curl --request GET \
--url https://app.asana.com/api/1.0/allocations/1206932836428797 \ 
--header 'accept: application/json' \ 
--header 'authorization: Bearer XXXXXXXX'

This returns the allocation created in the above POST example.

Here’s an example request for reading all allocations whose assignee is the user with gid 1205611053550793 and in a parent project with gid 1206741863479744:

curl --request GET \
--url https://app.asana.com/api/1.0/allocations/1206910013953663?assignee=1205611053550793&parent=1206741863479744 \ 
--header 'accept: application/json' \ 
--header 'authorization: Bearer XXXXXXXX'

This returns a list of allocations matching the given criteria.

Here’s an example of updating a few fields on an allocation:

curl --request PUT \ 
--url https://app.asana.com/api/1.0/allocations/1206932836428797 \ 
--header 'accept: application/json' \ 
--header 'authorization: Bearer XXXXXXXX' \ 
--header 'content-type: application/json' \ 
--data '{ "data": { "end_date": "2024-09-25","effort": { "type": "hours", "value": 25}}}'

This returns the updated allocation.

Here is an example of deleting an allocation:

curl --request DELETE \
--url https://app.asana.com/api/1.0/allocations/1206910013953663/1206932836428797 \ 
--header 'accept: application/json' \ 
--header 'authorization: Bearer XXXXXXXX'

This returns an empty JSON object.

Questions and Feedback

Please share any feedback or questions you may have!

5 Likes
2

Is there a way to create a webhook to trigger on add, remove, changes of an allocation?

3

Webhooks weren’t specifically mentioned in the announcement, so while Jeff or others from Asana can confirm, I would be 95% confident in saying that webhooks have not been added for allocations.

4

You are correct @Phil_Seeman. The initial allocations API release does not include events and webhooks. I have recommended that the eng team add them, but there is no timeline at this point.

2 Likes