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. Determines if the custom field is enabled or not.
`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"
  }
}