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.

Property	Type	Description
`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¦null	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.
`is_formula_field`	boolean	Conditional. 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.
» `{}`.`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¦null	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¦null	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.

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

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`asana_created_field`	string¦null	Conditional. A unique identifier to associate this field with the template source of truth.
`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.
`currency_code`	string¦null	ISO 4217 currency code to format this custom field. This will be `null` if the format is not `currency`.
`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_label_position`	string¦null	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`.
`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`.
`description`	string	Opt in. The description of the 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.
`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¦null	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.
`format`	string	The format of this 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.
`id_prefix`	string¦null	This field is the unique custom ID string for the custom field.
`is_formula_field`	boolean	Conditional. This flag describes whether a custom field is a formula 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.
`is_value_read_only`	boolean	Conditional. 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.
» `{}`.`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¦null	Conditional. 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.
» `{}`.`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.
`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.
`representation_type`	string	This field tells the type of the custom field. `text`, `enum`, `multi_enum`, `number`, `date`, `people`, `formula custom_id`
`resource_subtype`	string	The type of the custom field. Must be one of the given values.
`text_value`	string¦null	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.

{
  "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"
}

📘Premium feature

CustomFieldCompact

CustomField

📘
Premium feature