Portfolios

A portfolio gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple items, including a progress report and the most recent project status update.

Portfolios have some restrictions on size. Each portfolio has a maximum of 250 items and, like projects, a maximum of 20 custom fields.

Portfolios have the following fields:
Field Description
id 1234 Read-only. Globally unique ID of the portfolio. Note: This field is under active migration to the gid field—please see our blog post for more information.
gid "1234" Read-only. Globally unique ID of the portfolio.
resource_type "portfolio" Read-only. The resource type of this resource. The value for this resource is always portfolio.
name "Product launch" Name of the portfolio.
owner { id: 12345, gid: "12345", resource_type: "user", name: 'Tim Bizarro' } Read-only. The current owner of the portfolio. Cannot be null.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this portfolio was created.
created_by { id: 12345, gid: "12345", resource_type: "user", name: 'Tim Bizarro' } null Read-only. The user that created the portfolio.
custom_field_settings [ { id: 258147, gid: "258147", custom_field: {id: 1646, gid: "1646", name: "Priority", type: "enum"}, parent: {id: 36985, gid: "36985", name: "Product launch"} }, ...] Read-only. Array of custom field settings applied to the portfolio.
color "dark-red" "light-blue" "none" Must be either none or one of: dark-pink, dark-green, dark-blue, dark-red, dark-teal, dark-brown, dark-orange, dark-purple, dark-warm-gray, light-pink, light-green, light-blue, light-red, light-teal, light-yellow, light-orange, light-purple, light-warm-gray.
workspace { id: 14916, gid: "14916", name: 'My Workspace' } Create-only. The workspace or organization that the portfolio belongs to.
members [ { id: 1123, gid: "1123", resource_type: "user", name: 'Mittens' }, ... ] Members of the portfolio.

CREATE A PORTFOLIO

POST    /portfolios

Creates a new portfolio in the given workspace with the supplied name.

Note that portfolios created in the Asana UI may have some state (like the “Priority” custom field) which is automatically added to the portfolio when it is created. Portfolios created via our API will not be created with the same initial state to allow integrations to create their own starting state on a portfolio.

Parameter Description
workspace "1331" Required: The workspace or organization in which to create the portfolio.
name "Product launch" Required: The name of the newly-created portfolio
color "dark-red" "light-blue" "none" An optional color for the portfolio

GET A PORTFOLIO

GET    /portfolios/{portfolio_gid}

Returns the complete record for a single portfolio.

Parameter Description
portfolio_gid "36985" Required: The portfolio to get.

UPDATE A PORTFOLIO

PUT    /portfolios/{portfolio_gid}

An existing portfolio can be updated by making a PUT request on the URL for that portfolio. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged.

Returns the complete updated portfolio record.

Parameter Description
portfolio_gid "36985" Required: The portfolio to update.

DELETE A PORTFOLIO

DELETE    /portfolios/{portfolio_gid}

An existing portfolio can be deleted by making a DELETE request on the URL for that portfolio.

Returns an empty data record.

Parameter Description
portfolio_gid "36985" Required: The portfolio to delete.

QUERY FOR PORTFOLIOS

GET    /portfolios

Returns a list of the portfolios in compact representation that are owned by the current API user.

Parameter Description
workspace "1331" Required: The workspace or organization to filter portfolios on.
owner "14641" "me" "sashimi@asana.com" Required: The user who owns the portfolio. Currently, API users can only get a list of portfolios that they themselves own.

ITEMS IN A PORTFOLIO

GET    /portfolios/{portfolio_gid}/items

Get a list of the items in compact form in a portfolio.

Parameter Description
portfolio_gid "36985" Required: The portfolio from which to get the list of items.
POST    /portfolios/{portfolio_gid}/addItem

Add an item to a portfolio.

Returns an empty data block.

Parameter Description
portfolio_gid "36985" Required: The portfolio to which to add an item.
item "13579" Required: The item to add to the portfolio.
insert_before "13579" An id of an item in this portfolio. The new item will be added before the one specified here. insert_before and insert_after parameters cannot both be specified.
insert_after "13579" An id of an item in this portfolio. The new item will be added after the one specified here. insert_before and insert_after parameters cannot both be specified.
POST    /portfolios/{portfolio_gid}/removeItem

Remove an item to a portfolio.

Returns an empty data block.

Parameter Description
portfolio_gid "36985" Required: The portfolio from which to remove the item.
item "13579" Required: The item to remove from the portfolio.

WORK WITH PORTFOLIO MEMBERSHIPS

POST    /portfolios/{portfolio_gid}/addMembers

Adds the specified list of users as members of the portfolio. Returns the updated portfolio record.

Parameter Description
portfolio_gid "13579" Required: The portfolio to add members to.
members ["133713", "184253"] Required: An array of user ids.
POST    /portfolios/{portfolio_gid}/removeMembers

Removes the specified list of members from the portfolio. Returns the updated portfolio record.

Parameter Description
portfolio_gid "36985" Required: The portfolio to remove members from.
members ["133713", "184253"] Required: An array of user ids.

CUSTOM FIELDS ON A PORTFOLIO

GET    /portfolios/{portfolio_gid}/custom_field_settings

Get the custom field settings on a portfolio.

Parameter Description
portfolio_gid "36985" Required: The portfolio from which to get the custom field settings.
POST    /portfolios/{portfolio_gid}/addCustomFieldSetting

Create a new custom field setting on the portfolio. Returns the full record for the new custom field setting.

Parameter Description
portfolio_gid "36985" Required: The portfolio onto which to add the custom field.
custom_field "124578" Required: The id of the custom field to add to the portfolio.
is_important false Whether this field should be considered important to this portfolio (for instance, to display in the list view of items in the portfolio).
insert_before "258147" An id of a custom field setting on this portfolio. The new custom field setting will be added before this one. insert_before and insert_after parameters cannot both be specified.
insert_after "258147" An id of a custom field setting on this portfolio. The new custom field setting will be added after this one. insert_before and insert_after parameters cannot both be specified.
POST    /portfolios/{portfolio_gid}/removeCustomFieldSetting

Remove a custom field setting on the portfolio. Returns an empty data block.

Parameter Description
portfolio_gid "36985" Required: The portfolio from which to remove the custom field.
custom_field "124578" Required: The id of the custom field to remove from this portfolio.