Asana API

Getting access, Developing, Testing

Back to Asana

Get A Custom Field

Get the complete definition of a custom field’s metadata.

Since custom fields can be defined for one of a number of types, and these types have different data and behaviors, there are fields that are relevant to a particular type. For instance, as noted above, enum_options is only relevant for the enum type and defines the set of choices that the enum could represent. The examples below show some of these type-specific custom field definitions.

Input

type: object properties: parameters: type: object properties: custom_field_gid: type: string description: Globally unique identifier for the custom field. opt_pretty: type: boolean description: >- Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging. opt_fields: type: array items: type: string description: >- Defines fields to return. Some requests return *compact* representations of objects in order to conserve resources and complete the request more efficiently. Other times requests return more information than you may need. This option allows you to list the exact set of fields that the API should be sure to return for the objects. The field names should be provided as paths, described below. The id of included objects will always be returned, regardless of the field options. required: - custom_field_gid title: Parameters

Output

type: object properties: data: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: description: The name of the custom field. type: string example: Status resource_subtype: description: | The type of the custom field. Must be one of the given values. type: string example: text enum: - text - enum - multi_enum - number - date - people type: description: > *Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values. type: string readOnly: true enum: - text - enum - multi_enum - number enum_options: description: >- *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](/reference/createenumoptionforcustomfield). type: array items: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: description: The name of the enum option. type: string example: Low enabled: description: >- Whether or not the enum option is a selectable value for the custom field. type: boolean example: true color: description: The color of the enum option. Defaults to ‘none’. type: string example: blue enabled: description: '*Conditional*. Determines if the custom field is enabled or not.' type: boolean example: true date_value: type: object properties: date: type: string description: A string representing the date in YYYY-MM-DD format. example: '2024-08-23T00:00:00.000Z' date_time: type: string description: >- A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`. example: '2024-08-23T22:00:00.000Z' enum_value: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: description: The name of the enum option. type: string example: Low enabled: description: >- Whether or not the enum option is a selectable value for the custom field. type: boolean example: true color: description: The color of the enum option. Defaults to ‘none’. type: string example: blue multi_enum_values: description: >- *Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field. type: array items: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: description: The name of the enum option. type: string example: Low enabled: description: >- Whether or not the enum option is a selectable value for the custom field. type: boolean example: true color: description: The color of the enum option. Defaults to ‘none’. type: string example: blue number_value: description: '*Conditional*. This number is the value of a `number` custom field.' type: number example: 5.2 text_value: description: '*Conditional*. This string is the value of a `text` custom field.' type: string example: Some Value display_value: description: >- 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. type: string readOnly: true example: blue nullable: true description: description: >- [Opt In](/docs/inputoutput-options). The description of the custom field. type: string example: Development team priority precision: description: >- 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. type: integer example: 2 format: description: The format of this custom field. type: string enum: - currency - identifier - percentage - custom - none example: custom currency_code: description: >- ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`. type: string nullable: true example: EUR custom_label: description: >- This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`. type: string nullable: true example: gold pieces custom_label_position: description: >- 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`. type: string enum: - prefix - suffix example: suffix is_global_to_workspace: description: >- 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. type: boolean example: true readOnly: true has_notifications_enabled: description: >- *Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field. type: boolean example: true asana_created_field: description: >- *Conditional*. A unique identifier to associate this field with the template source of truth. type: string readOnly: true nullable: true enum: - 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 - 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 example: priority created_by: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: type: string description: '*Read-only except when same user as requester*. The user’s name.' example: Greg Sanchez people_value: description: >- *Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](/reference/users) objects reflects the values of a `people` custom field. type: array items: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: type: string description: '*Read-only except when same user as requester*. The user’s name.' example: Greg Sanchez