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