Custom field settings

Custom fields are attached to a particular project with the custom field settings resource. This resource both represents the many-to-many join of the custom field and project as well as stores information that is relevant to that particular pairing. For instance, the is_important property determines some possible application-specific handling of that custom field.

Related references

HTTP method	API endpoint	Description
`POST`	/projects/{project_gid}/addCustomFieldSetting	Custom fields are associated with projects by way of custom field settings. This method creates a setting for the project.
`POST`	/projects/{project_gid}/removeCustomFieldSetting	Removes a custom field setting from a project.
`POST`	/portfolios/{portfolio_gid}/addCustomFieldSetting	Custom fields are associated with portfolios by way of custom field settings. This method creates a setting for the portfolio.
`POST`	/portfolios/{portfolio_gid}/removeCustomFieldSetting	Removes a custom field setting from a portfolio.

CustomFieldSettingCompact

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.

{
  "gid": "12345",
  "resource_type": "custom_field_setting"
}

CustomFieldSetting

Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.

Property	Type	Description
`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`.`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.

{
  "gid": "12345",
  "resource_type": "custom_field_setting",
  "custom_field": {
    "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"
  },
  "is_important": false,
  "parent": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy"
  },
  "project": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy"
  }
}