Custom fields

📘

Premium feature

Custom fields are a premium feature. Integrations which work with custom fields need to handle an assortment of use cases for free and premium users in context of free and premium organizations.

To get started with custom fields, visit this guide.

CustomFieldCompact

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.
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_valueobject¦nullConditional. 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.
is_formula_fieldbooleanConditional. This flag describes whether a custom field is a formula 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.
namestringThe name of the custom field.
number_valuenumber¦nullConditional. 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_valuestring¦nullConditional. 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.
{
  "gid": "12345",
  "resource_type": "custom_field",
  "date_value": {
    "date": "2024-08-23",
    "date_time": "2024-08-23T22:00:00.000Z"
  },
  "display_value": "blue",
  "enabled": true,
  "enum_options": [
    {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    }
  ],
  "enum_value": {
    "gid": "12345",
    "resource_type": "enum_option",
    "color": "blue",
    "enabled": true,
    "name": "Low"
  },
  "multi_enum_values": [
    {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    }
  ],
  "name": "Status",
  "number_value": 5.2,
  "resource_subtype": "text",
  "text_value": "Some Value",
  "type": "text"
}

CustomField

Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the custom fields developer documentation for more information about how custom fields relate to various resources in Asana.

Users in Asana can lock custom fields, which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code 403 Forbidden.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
asana_created_fieldstring¦nullConditional. A unique identifier to associate this field with the template source of truth.
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.
currency_codestring¦nullISO 4217 currency code to format this custom field. This will be null if the format is not currency.
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_label_positionstring¦nullOnly 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.
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.
descriptionstringOpt in. The description of the 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.
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_valueobject¦nullConditional. 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.
formatstringThe format of this 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.
id_prefixstring¦nullThis field is the unique custom ID string for the custom field.
is_formula_fieldbooleanConditional. This flag describes whether a custom field is a formula custom field.
is_global_to_workspacebooleanThis flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.
is_value_read_onlybooleanConditional. This flag describes whether a custom field is read only.
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_valuenumber¦nullConditional. This number is the value of a number 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.
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.
representation_typestringThis field tells the type of the custom field.

text, enum, multi_enum, number, date, people, formula custom_id
resource_subtypestringThe type of the custom field. Must be one of the given values.
text_valuestring¦nullConditional. 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.
{
  "gid": "12345",
  "resource_type": "custom_field",
  "asana_created_field": "priority",
  "created_by": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  },
  "currency_code": "EUR",
  "custom_label": "gold pieces",
  "custom_label_position": "suffix",
  "date_value": {
    "date": "2024-08-23",
    "date_time": "2024-08-23T22:00:00.000Z"
  },
  "description": "Development team priority",
  "display_value": "blue",
  "enabled": true,
  "enum_options": [
    {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    }
  ],
  "enum_value": {
    "gid": "12345",
    "resource_type": "enum_option",
    "color": "blue",
    "enabled": true,
    "name": "Low"
  },
  "format": "custom",
  "has_notifications_enabled": true,
  "is_global_to_workspace": true,
  "multi_enum_values": [
    {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    }
  ],
  "name": "Status",
  "number_value": 5.2,
  "people_value": [
    {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    }
  ],
  "precision": 2,
  "resource_subtype": "text",
  "text_value": "Some Value",
  "type": "text"
}