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

📘
Size limits
Portfolios have some restrictions on size. Each portfolio has a max of 1500 items and, like projects, a maximum of 20 custom fields.

PortfolioCompact

A Compact object reflects the default fields returned after a successful API request. See input/output options to include more fields in the response.

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`name`	string	The name of the portfolio.

{
  "gid": "12345",
  "resource_type": "portfolio",
  "name": "Bug Portfolio"
}

Portfolio

📘
200 response schema
For another view of a full portfolio schema, see the example 200 responses when getting a portfolio.

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`archived`	boolean	Opt in . True if the portfolio is archived, false if not. Archived portfolios do not show in the UI by default and may be treated differently for queries.
`color`	string	Color of the portfolio.
`name`	string	The name of the portfolio.
`created_at`	string(date-time)	The time at which this resource was created.
`created_by`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
`created_by`.`gid`	string	Globally unique identifier of the resource, as a string.
`created_by`.`resource_type`	string	The base type of this resource.
`created_by`.`name`	string	Read-only except when same user as requester. The user’s name.
`current_status_update`	object	A status update is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the project.
`current_status_update`.`gid`	string	Globally unique identifier of the resource, as a string.
`current_status_update`.`resource_type`	string	The base type of this resource.
`current_status_update`.`resource_subtype`	string	The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning. The `resource_subtypes` for `status` objects represent the type of their parent.
`current_status_update`.`title`	string	The title of the status update.
`custom_field_settings`	[object]	Array of custom field settings applied to the portfolio.
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`	object	The custom field that is applied to the `parent`.
» `{}`.`custom_field`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`custom_field`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`.`asana_created_field`	string¦null	Conditional. A unique identifier to associate this field with the template source of truth.
» `{}`.`custom_field`.`created_by`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
» `{}`.`custom_field`.`created_by`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`custom_field`.`created_by`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`.`created_by`.`name`	string	Read-only except when same user as requester. The user’s name.
» `{}`.`custom_field`.`currency_code`	string¦null	ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.
» `{}`.`custom_field`.`custom_label`	string¦null	This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`.
» `{}`.`custom_field`.`custom_label_position`	string	Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`.
» `{}`.`custom_field`.`date_value`	object	Conditional. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.
» `{}`.`custom_field`.`date_value`.`date`	string	A string representing the date in YYYY-MM-DD format.
» `{}`.`custom_field`.`date_value`.`date_time`	string	A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.
» `{}`.`custom_field`.`description`	string	Opt in. The description of the custom field.
» `{}`.`custom_field`.`display_value`	string¦null	A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.
» `{}`.`custom_field`.`enabled`	boolean	Conditional. Determines if the custom field is enabled or not.
» `{}`.`custom_field`.`enum_options`	[object]	Conditional. Only relevant for custom fields of type `enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to working with enum options.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`custom_field`.`enum_value`	object	Conditional. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field.
» `{}`.`custom_field`.`enum_value`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`custom_field`.`enum_value`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`.`enum_value`.`color`	string	The color of the enum option. Defaults to `none`.
» `{}`.`custom_field`.`enum_value`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
» `{}`.`custom_field`.`enum_value`.`name`	string	The name of the enum option.
» `{}`.`custom_field`.`format`	string	The format of this custom field.
» `{}`.`custom_field`.`has_notifications_enabled`	boolean	Conditional. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.
» `{}`.`custom_field`.`is_global_to_workspace`	boolean	This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.
» `{}`.`custom_field`.`multi_enum_values`	[object]	`Conditional`. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`custom_field`.`name`	string	The name of the custom field.
» `{}`.`custom_field`.`number_value`	number	Conditional. This number is the value of a `number` custom field.
» `{}`.`custom_field`.`people_value`	[object]	Conditional. Only relevant for custom fields of type `people`. This array of compact user objects reflects the values of a `people` custom field.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`name`	string	Read-only except when same user as requester. The user’s name.
» `{}`.`custom_field`.`precision`	integer	Only relevant for custom fields of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive. For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%. The identifier format will always have a precision of 0.
» `{}`.`custom_field`.`resource_subtype`	string	The type of the custom field. Must be one of the given values.
» `{}`.`custom_field`.`text_value`	string	Conditional. This string is the value of a `text` custom field.
» `{}`.`custom_field`.`type`	string	Deprecated: new integrations should prefer the `resource_subtype` field. The type of the custom field. Must be one of the given values.
» `{}`.`is_important`	boolean	`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.
» `{}`.`parent`	object	The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.
» `{}`.`parent`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`parent`.`resource_type`	string	The base type of this resource.
» `{}`.`parent`.`name`	string	Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
» `{}`.`project`	object	Deprecated: new integrations should prefer the `parent` field. The id of the project that this custom field settings refers to.
» `{}`.`project`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`project`.`resource_type`	string	The base type of this resource.
» `{}`.`project`.`name`	string	Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
`custom_fields`	[object]	Array of custom fields
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`date_value`	object	Conditional. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`.
» `{}`.`date_value`.`date`	string	A string representing the date in YYYY-MM-DD format.
» `{}`.`date_value`.`date_time`	string	A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.
» `{}`.`display_value`	string¦null	A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.
» `{}`.`enabled`	boolean	Conditional. Determines if the custom field is enabled or not.
» `{}`.`enum_options`	[object]	Conditional. Only relevant for custom fields of type `enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to working with enum options.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`enum_value`	object	Conditional. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field.
» `{}`.`enum_value`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`enum_value`.`resource_type`	string	The base type of this resource.
» `{}`.`enum_value`.`color`	string	The color of the enum option. Defaults to `none`.
» `{}`.`enum_value`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
» `{}`.`enum_value`.`name`	string	The name of the enum option.
» `multi_enum_values`	[object]	Conditional. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`name`	string	The name of the custom field.
» `{}`.`number_value`	number	Conditional. This number is the value of a `number` custom field.
» `{}`.`resource_subtype`	string	The type of the custom field. Must be one of the given values.
» `{}`.`text_value`	string	Conditional. This string is the value of a `text` custom field.
» `{}`.`type`	string	Deprecated: new integrations should prefer the `resource_subtype` field. The type of the custom field. Must be one of the given values.
`default_access_level`	string	The default access level when inviting new members to the portfolio `admin`, `editor`, `viewer`
`due_on`	string(date-time)¦null	The localized day on which this portfolio is due. This takes a date with format YYYY-MM-DD.
`members`	[object]	none
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`name`	string	Read-only except when same user as requester. The user’s name.
`owner`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
`owner`.`gid`	string	Globally unique identifier of the resource, as a string.
`owner`.`resource_type`	string	The base type of this resource.
`owner`.`name`	string	Read-only except when same user as requester. The user’s name.
`permalink_url`	string	A url that points directly to the object within Asana.
`privacy_setting`	string	The privacy setting of the portfolio. Note: Administrators in your organization may restrict the values of `privacy_setting`. `public_to_domain`, `members_only`
`project_templates`	[object]	Array of project templates that are in the portfolio
`{}.gid`	string	Globally unique identifier of the resource, as a string.
`{}.resource_type`	string	The base type of this resource.
`{}.name`	string	Name of the project template.
`public`	boolean	True if the portfolio is public to its workspace members.
`start_on`	string(date)¦null	The day on which work for this portfolio begins, or null if the portfolio has no start date. This takes a date with `YYYY-MM-DD` format. `due_on` must be present in the request when setting or unsetting the `start_on` parameter. Additionally, `start_on` and `due_on` cannot be the same date.
`workspace`	object	Create-only. The workspace or organization that the portfolio belongs to.
`workspace`.`gid`	string	Globally unique identifier of the resource, as a string.
`workspace`.`resource_type`	string	The base type of this resource.
`workspace`.`name`	string	The name of the workspace.

{
  "gid": "12345",
  "resource_type": "portfolio",
  "name": "Bug Portfolio",
  "color": "light-green",
  "created_at": "2012-02-22T02:06:58.147Z",
  "created_by": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Greg Sanchez"
  },
  "custom_field_settings": [
    {
      "gid": "12345",
      "resource_type": "task",
      "project": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Stuff to buy"
      },
      "is_important": false,
      "parent": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Stuff to buy"
      },
      "custom_field": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Status",
        "resource_subtype": "text",
        "type": "text",
        "enum_options": [
          {
            "gid": "12345",
            "resource_type": "task",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "enabled": true,
        "representation_type": "number",
        "id_prefix": "ID",
        "is_formula_field": false,
        "date_value": {
          "date": "2024-08-23",
          "date_time": "2024-08-23T22:00:00.000Z"
        },
        "enum_value": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Low",
          "enabled": true,
          "color": "blue"
        },
        "multi_enum_values": [
          {
            "gid": "12345",
            "resource_type": "task",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "number_value": 5.2,
        "text_value": "Some Value",
        "display_value": "blue",
        "description": "Development team priority",
        "precision": 2,
        "format": "custom",
        "currency_code": "EUR",
        "custom_label": "gold pieces",
        "custom_label_position": "suffix",
        "is_global_to_workspace": true,
        "has_notifications_enabled": true,
        "asana_created_field": "priority",
        "is_value_read_only": false,
        "created_by": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Greg Sanchez"
        },
        "people_value": [
          {
            "gid": "12345",
            "resource_type": "task",
            "name": "Greg Sanchez"
          }
        ]
      }
    }
  ],
  "current_status_update": {
    "gid": "12345",
    "resource_type": "task",
    "title": "Status Update - Jun 15",
    "resource_subtype": "project_status_update"
  },
  "due_on": "2019-09-15",
  "custom_fields": [
    {
      "gid": "12345",
      "resource_type": "task",
      "name": "Status",
      "resource_subtype": "text",
      "type": "text",
      "enum_options": [
        {
          "gid": "12345",
          "resource_type": "task",
          "name": "Low",
          "enabled": true,
          "color": "blue"
        }
      ],
      "enabled": true,
      "representation_type": "number",
      "id_prefix": "ID",
      "is_formula_field": false,
      "date_value": {
        "date": "2024-08-23",
        "date_time": "2024-08-23T22:00:00.000Z"
      },
      "enum_value": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Low",
        "enabled": true,
        "color": "blue"
      },
      "multi_enum_values": [
        {
          "gid": "12345",
          "resource_type": "task",
          "name": "Low",
          "enabled": true,
          "color": "blue"
        }
      ],
      "number_value": 5.2,
      "text_value": "Some Value",
      "display_value": "blue"
    }
  ],
  "members": [
    {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    }
  ],
  "owner": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Greg Sanchez"
  },
  "start_on": "2019-09-14",
  "workspace": {
    "gid": "12345",
    "resource_type": "task",
    "name": "My Company Workspace"
  },
  "permalink_url": "https://app.asana.com/0/resource/123456789/list",
  "public": false,
  "default_access_level": "viewer",
  "privacy_setting": "members_only",
  "project_templates": [
    {
      "gid": "12345",
      "resource_type": "task",
      "name": "Packing list"
    }
  ]
}

Portfolios

📘
Size limits

PortfolioCompact

Portfolio

📘
`200` response schema

📘Size limits

PortfolioCompact

Portfolio

📘200 response schema

📘
Size limits

📘
`200` response schema