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

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.

Example JSON for CustomFieldSettingCompact:

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

CustomFieldSetting

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`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.
`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.
`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.name`	string	The name of the 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. Click to show all enum values `date` `enum` `multi_enum` `number` `people` `text`
`custom_field.enum_options[]`	[object]	Conditional. Only relevant for custom fields of type `enum` or `multi_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.
`custom_field.enum_options[].gid`	string	Globally unique identifier of the resource, as a string.
`custom_field.enum_options[].resource_type`	string	The base type of this resource.
`custom_field.enum_options[].name`	string	The name of the enum option.
`custom_field.enum_options[].enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`custom_field.enum_options[].color`	string	The color of the enum option. Defaults to `none`.
`custom_field.enabled`	boolean	Conditional. This field applies only to custom field values and is not available for custom field definitions. Determines if the custom field is enabled or not. For more details, see the Custom Fields documentation.
`custom_field.representation_type`	string	This field tells the type of the custom field. Click to show all enum values `custom_id` `date` `enum` `formula` `multi_enum` `number` `people` `reference` `text`
`custom_field.id_prefix`	string	This field is the unique custom ID string for the custom field.
`custom_field.input_restrictions[]`	[string]	Conditional. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.
`custom_field.is_formula_field`	boolean	Conditional. This flag describes whether a custom field is a formula custom field.
`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_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.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.name`	string	The name of the enum option.
`custom_field.enum_value.enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`custom_field.enum_value.color`	string	The color of the enum option. Defaults to `none`.
`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.
`custom_field.multi_enum_values[].gid`	string	Globally unique identifier of the resource, as a string.
`custom_field.multi_enum_values[].resource_type`	string	The base type of this resource.
`custom_field.multi_enum_values[].name`	string	The name of the enum option.
`custom_field.multi_enum_values[].enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`custom_field.multi_enum_values[].color`	string	The color of the enum option. Defaults to `none`.
`custom_field.number_value`	number	Conditional. This number is the value of a `number` custom field.
`custom_field.text_value`	string	Conditional. This string is the value of a `text` custom field.
`custom_field.display_value`	string	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.description`	string	Opt In. The description of the custom field.
`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.format`	string	The format of this custom field. Click to show all enum values `currency` `custom` `duration` `identifier` `none` `percentage`
`custom_field.currency_code`	string	ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.
`custom_field.custom_label`	string	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`. Click to show all enum values `null` `prefix` `suffix`
`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.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.asana_created_field`	string	Conditional. A unique identifier to associate this field with the template source of truth. Click to show all enum values `a_v_requirements` `account_name` `actionable` `align_shipping_link` `align_status` `allotted_time` `appointment` `approval_stage` `approved` `article_series` `board_committee` `browser` `campaign_audience` `campaign_project_status` `campaign_regions` `channel_primary` `client_topic_type` `complete_by` `contact` `contact_email_address` `content_channels` `content_channels_needed` `content_stage` `content_type` `contract` `contract_status` `cost` `creation_stage` `creative_channel` `creative_needed` `creative_needs` `data_sensitivity` `deal_size` `delivery_appt` `delivery_appt_date` `department` `department_responsible` `design_request_needed` `design_request_type` `discussion_category` `do_this_task` `editorial_content_status` `editorial_content_tag` `editorial_content_type` `effort` `effort_level` `est_completion_date` `estimated_time` `estimated_value` `expected_cost` `external_steps_needed` `favorite_idea` `feedback_type` `financial` `funding_amount` `grant_application_process` `hiring_candidate_status` `idea_status` `ids_link` `ids_patient_link` `implementation_stage` `insurance` `interview_area` `interview_question_score` `itero_scan_link` `job_s_applied_to` `lab` `launch_status` `lead_status` `localization_language` `localization_market_team` `localization_status` `meeting_minutes` `meeting_needed` `minutes` `mrr` `must_localize` `name_of_foundation` `need_to_follow_up` `next_appointment` `next_steps_sales` `null` `num_people` `number_of_user_reports` `office_location` `onboarding_activity` `owner` `participants_needed` `patient_date_of_birth` `patient_email` `patient_phone` `patient_status` `phone_number` `planning_category` `point_of_contact` `position` `post_format` `prescription` `priority` `priority_level` `product` `product_stage` `progress` `project_size` `project_status` `proposed_budget` `publish_status` `reason_for_scan` `referral` `request_type` `research_status` `responsible_department` `responsible_team` `risk_assessment_status` `room_name` `sales_counterpart` `sentiment` `shipping_link` `social_channels` `stage` `status` `status_design` `status_of_initiative` `system_setup` `task_progress` `team` `team_marketing` `team_responsible` `time_it_takes_to_complete_tasks` `timeframe` `treatment_type` `type_work_requests_it` `use_agency` `user_name` `vendor_category` `vendor_type` `word_count`
`custom_field.is_value_read_only`	boolean	Conditional. This flag describes whether a custom field is read only.
`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.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.
`custom_field.people_value[].gid`	string	Globally unique identifier of the resource, as a string.
`custom_field.people_value[].resource_type`	string	The base type of this resource.
`custom_field.people_value[].name`	string	Read-only except when same user as requester. The user's name.
`custom_field.reference_value[]`	[object]	Conditional. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.
`custom_field.reference_value[].gid`	string	Globally unique identifier of the resource, as a string.
`custom_field.reference_value[].resource_type`	string	The base type of this resource.
`custom_field.reference_value[].name`	string	The name of the object.
`custom_field.privacy_setting`	string	The privacy setting of the custom field. Note: Administrators in your organization may restrict the values of `privacy_setting`. Click to show all enum values `private` `public` `public_with_guests`
`custom_field.default_access_level`	string	The default access level when inviting new members to the custom field. This isn't applied when the `privacy_setting` is `private`, or the user is a guest. For local fields in a project or portfolio, the user must additionally have permission to modify the container itself. Click to show all enum values `admin` `editor` `user`
`custom_field.resource_subtype`	string	The type of the custom field. Must be one of the given values. Click to show all enum values `date` `enum` `multi_enum` `number` `people` `reference` `text`

Example JSON for CustomFieldSetting:

{
  "gid": "12345",
  "resource_type": "custom_field_setting",
  "project": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy"
  },
  "is_important": false,
  "parent": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy"
  },
  "custom_field": {
    "gid": "12345",
    "resource_type": "custom_field",
    "name": "Status",
    "type": "example string",
    "enum_options": [
      {
        "gid": "12345",
        "resource_type": "enum_option",
        "name": "Low",
        "enabled": true,
        "color": "blue"
      }
    ],
    "enabled": true,
    "representation_type": "number",
    "id_prefix": "ID",
    "input_restrictions": "task",
    "is_formula_field": false,
    "date_value": {
      "date": "2024-08-23",
      "date_time": "2024-08-23T22:00:00.000Z"
    },
    "enum_value": {
      "gid": "12345",
      "resource_type": "enum_option",
      "name": "Low",
      "enabled": true,
      "color": "blue"
    },
    "multi_enum_values": [
      {
        "gid": "12345",
        "resource_type": "enum_option",
        "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",
    "is_value_read_only": false,
    "created_by": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "people_value": [
      {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    ],
    "reference_value": [
      {
        "gid": "12345",
        "resource_type": "task",
        "name": "Bug Task"
      }
    ],
    "privacy_setting": "public_with_guests",
    "default_access_level": "user",
    "resource_subtype": "text"
  }
}