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

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
namestringThe 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.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
colorstringColor of the portfolio.
namestringThe name of the portfolio.
created_atstring(date-time)The time at which this resource was created.
created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
created_by.gidstringGlobally unique identifier of the resource, as a string.
created_by.resource_typestringThe base type of this resource.
created_by.namestringRead-only except when same user as requester. The user’s name.
current_status_updateobjectA 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.gidstringGlobally unique identifier of the resource, as a string.
current_status_update.resource_typestringThe base type of this resource.
current_status_update.resource_subtypestringThe 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.titlestringThe title of the status update.
custom_field_settings[object]Array of custom field settings applied to the portfolio.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.custom_fieldobjectThe custom field that is applied to the parent.
» {}.custom_field.gidstringGlobally unique identifier of the resource, as a string.
» {}.custom_field.resource_typestringThe base type of this resource.
» {}.custom_field.asana_created_fieldstring¦nullConditional. A unique identifier to associate this field with the template source of truth.
» {}.custom_field.created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
» {}.custom_field.created_by.gidstringGlobally unique identifier of the resource, as a string.
» {}.custom_field.created_by.resource_typestringThe base type of this resource.
» {}.custom_field.created_by.namestringRead-only except when same user as requester. The user’s name.
» {}.custom_field.currency_codestring¦nullISO 4217 currency code to format this custom field. This will be null if the format is not currency.
» {}.custom_field.custom_labelstring¦nullThis 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_positionstringOnly 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_valueobjectConditional. 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.datestringA string representing the date in YYYY-MM-DD format.
» {}.custom_field.date_value.date_timestringA string representing the date in ISO 8601 format. If no time value is selected, the value of date-time will be null.
» {}.custom_field.descriptionstringOpt in. The description of the custom field.
» {}.custom_field.display_valuestring¦nullA 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.enabledbooleanConditional. 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.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.custom_field.enum_valueobjectConditional. Only relevant for custom fields of type enum. This object is the chosen value of an enum custom field.
» {}.custom_field.enum_value.gidstringGlobally unique identifier of the resource, as a string.
» {}.custom_field.enum_value.resource_typestringThe base type of this resource.
» {}.custom_field.enum_value.colorstringThe color of the enum option. Defaults to none.
» {}.custom_field.enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.custom_field.enum_value.namestringThe name of the enum option.
» {}.custom_field.formatstringThe format of this custom field.
» {}.custom_field.has_notifications_enabledbooleanConditional. 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 booleanThis 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.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.custom_field.namestringThe name of the custom field.
» {}.custom_field.number_valuenumberConditional. 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.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.namestringRead-only except when same user as requester. The user’s name.
» {}.custom_field.precisionintegerOnly 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_subtypestringThe type of the custom field. Must be one of the given values.
» {}.custom_field.text_valuestringConditional. This string is the value of a text custom field.
» {}.custom_field.typestringDeprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values.
» {}.is_importantbooleanis_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.
» {}.parentobjectThe 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.gidstringGlobally unique identifier of the resource, as a string.
» {}.parent.resource_typestringThe base type of this resource.
» {}.parent.namestringName 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.
» {}.projectobjectDeprecated: new integrations should prefer the parent field. The id of the project that this custom field settings refers to.
» {}.project.gidstringGlobally unique identifier of the resource, as a string.
» {}.project.resource_typestringThe base type of this resource.
» {}.project.namestringName 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
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.date_valueobjectConditional. 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.datestringA string representing the date in YYYY-MM-DD format.
» {}.date_value.date_timestringA string representing the date in ISO 8601 format. If no time value is selected, the value of date-time will be null.
» {}.display_valuestring¦nullA 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.
» {}.enabledbooleanConditional. 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.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.enum_valueobjectConditional. Only relevant for custom fields of type enum. This object is the chosen value of an enum custom field.
» {}.enum_value.gidstringGlobally unique identifier of the resource, as a string.
» {}.enum_value.resource_typestringThe base type of this resource.
» {}.enum_value.colorstringThe color of the enum option. Defaults to none.
» {}.enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.enum_value.namestringThe 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.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.namestringThe name of the custom field.
» {}.number_valuenumberConditional. This number is the value of a number custom field.
» {}.resource_subtypestringThe type of the custom field. Must be one of the given values.
» {}.text_valuestringConditional. This string is the value of a text custom field.
» {}.typestringDeprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values.
due_onstring(date-time)¦nullThe localized day on which this portfolio is due. This takes a date with format YYYY-MM-DD.
members[object]none
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.namestringRead-only except when same user as requester. The user’s name.
ownerobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
owner.gidstringGlobally unique identifier of the resource, as a string.
owner.resource_typestringThe base type of this resource.
owner.namestringRead-only except when same user as requester. The user’s name.
permalink_urlstringA url that points directly to the object within Asana.
publicbooleanTrue if the portfolio is public to its workspace members.
start_onstring(date)¦nullThe 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.
workspaceobjectCreate-only. The workspace or organization that the portfolio belongs to.
workspace.gidstringGlobally unique identifier of the resource, as a string.
workspace.resource_typestringThe base type of this resource.
workspace.namestringThe name of the workspace.
{
  "data": {
    "gid": "12345",
    "resource_type": "task",
    "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,
          "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",
          "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,
        "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
  }
}