📘
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

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`name`	string	The name of the 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`
`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.
`enum_options[].gid`	string	Globally unique identifier of the resource, as a string.
`enum_options[].resource_type`	string	The base type of this resource.
`enum_options[].name`	string	The name of the enum option.
`enum_options[].enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`enum_options[].color`	string	The color of the enum option. Defaults to `none`.
`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.
`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` `text`
`id_prefix`	string	This field is the unique custom ID string for the 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.
`is_formula_field`	boolean	Conditional. This flag describes whether a custom field is a formula 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`.
`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`.
`enum_value`	object	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.name`	string	The name of the enum option.
`enum_value.enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`enum_value.color`	string	The color of the enum option. Defaults to `none`.
`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.
`multi_enum_values[].gid`	string	Globally unique identifier of the resource, as a string.
`multi_enum_values[].resource_type`	string	The base type of this resource.
`multi_enum_values[].name`	string	The name of the enum option.
`multi_enum_values[].enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`multi_enum_values[].color`	string	The color of the enum option. Defaults to `none`.
`number_value`	number	Conditional. This number is the value of a `number` custom field.
`text_value`	string	Conditional. This string is the value of a `text` 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.

Example JSON for CustomFieldCompact:

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

CustomField

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`name`	string	The name of the 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`
`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.
`enum_options[].gid`	string	Globally unique identifier of the resource, as a string.
`enum_options[].resource_type`	string	The base type of this resource.
`enum_options[].name`	string	The name of the enum option.
`enum_options[].enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`enum_options[].color`	string	The color of the enum option. Defaults to `none`.
`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.
`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`
`id_prefix`	string	This field is the unique custom ID string for the 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.
`is_formula_field`	boolean	Conditional. This flag describes whether a custom field is a formula 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`.
`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`.
`enum_value`	object	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.name`	string	The name of the enum option.
`enum_value.enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`enum_value.color`	string	The color of the enum option. Defaults to `none`.
`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.
`multi_enum_values[].gid`	string	Globally unique identifier of the resource, as a string.
`multi_enum_values[].resource_type`	string	The base type of this resource.
`multi_enum_values[].name`	string	The name of the enum option.
`multi_enum_values[].enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
`multi_enum_values[].color`	string	The color of the enum option. Defaults to `none`.
`number_value`	number	Conditional. This number is the value of a `number` custom field.
`text_value`	string	Conditional. This string is the value of a `text` 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.
`description`	string	Opt In. The description of the 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.
`format`	string	The format of this custom field. Click to show all enum values `currency` `custom` `duration` `identifier` `none` `percentage`
`currency_code`	string	ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.
`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_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`
`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.
`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.
`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`
`is_value_read_only`	boolean	Conditional. This flag describes whether a custom field is read only.
`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.
`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.
`people_value[].gid`	string	Globally unique identifier of the resource, as a string.
`people_value[].resource_type`	string	The base type of this resource.
`people_value[].name`	string	Read-only except when same user as requester. The user's name.
`reference_value[]`	[object]	Conditional. Only relevant for custom fields of type `reference`. This array of objects reflects the values of a `reference` custom field.
`reference_value[].gid`	string	Globally unique identifier of the resource, as a string.
`reference_value[].resource_type`	string	The base type of this resource.
`reference_value[].name`	string	The name of the object.
`html_text_value`	string	Conditional. Only relevant for custom fields of type `text`. This is the HTML representation of the text value of a custom field, corresponding to the `text_value` plain-text 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`
`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`
`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 CustomField:

{
  "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"
    }
  ],
  "html_text_value": "<body>Some Value</body>",
  "privacy_setting": "public_with_guests",
  "default_access_level": "user",
  "resource_subtype": "text"
}