Back to AsanaUpdate A Custom Field
A specific, existing custom field can be updated by making a PUT request on the URL for that custom field. Only the fields provided in the data
block will be updated; any unspecified fields will remain unchanged
When using this method, it is best to specify only those fields you wish to change, or else you may overwrite changes made by another user since you last retrieved the custom field.
A custom field’s type
cannot be updated.
An enum custom field’s enum_options
cannot be updated with this endpoint. Instead see “Work With Enum Options” for information on how to update enum_options
.
Locked custom fields can only be updated by the user who locked the field.
Returns the complete updated custom field record.
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
data:
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
workspace:
type: string
description: '*Create-Only* The workspace to create a custom field in.'
example: '1331'
owned_by_app:
type: boolean
description: >-
*Allow-listed*. Instructs the API that this Custom Field is
app-owned. This parameter is allow-listed to specific apps at this
point in time. For apps that are not allow-listed, providing this
parameter will result in a `403 Forbidden`.
people_value:
type: array
items:
type: string
title: Data
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