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 projects, including a progress report and the most recent project status update.

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.
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.

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 (projects) 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 (project) 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 (project) to add to the portfolio.
insert_before "13579" An id of an item (project) 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 (project) 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 (project) 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 (project) to remove from the portfolio.

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.