Asana
  1. Custom Fields
Asana
  • Attachments
    • Delete an attachment
      DELETE
    • Get an attachment
      GET
    • Get attachments for a task
      GET
    • Upload an attachment
      POST
  • Batch API
    • Submit parallel requests
      POST
  • Custom Fields
    • Create a custom field
      POST
    • Delete a custom field
      DELETE
    • Get a custom field
      GET
    • Update a custom field
      PUT
    • Create an enum option
      POST
    • Reorder a custom field's enum
      POST
    • Update an enum option
      PUT
    • Get a workspace's custom fields
      GET
  • Events
    • Get events on a resource
      GET
  • Goals
    • Get goals
      GET
    • Create a goal
      POST
    • Delete a goal
      DELETE
    • Get a goal
      GET
    • Update a goal
      PUT
    • Add a collaborator to a goal
      POST
    • Add a subgoal to a parent goal
      POST
    • Add a project/portfolio as supporting work for a goal.
      POST
    • Get parent goals from a goal
      GET
    • Remove a collaborator from a goal
      POST
    • Remove a subgoal from a goal
      POST
    • Remove a project/portfolio as supporting work for a goal.
      POST
    • Create a goal metric
      POST
    • Update a goal metric
      POST
    • Get subgoals from a goal
      GET
    • Get supporting work from a goal
      GET
  • Jobs
    • Get a job by id
  • Organization Exports
    • Create an organization export request
    • Get details on an org export request
  • Teams
    • Get teams in an organization
    • Create a team
    • Get a team
    • Add a user to a team
    • Remove a user from a team
    • Get teams for a user
  • Portfolio Memberships
    • Get multiple portfolio memberships
    • Get a portfolio membership
    • Get memberships from a portfolio
  • Portfolios
    • Get multiple portfolios
    • Create a portfolio
    • Delete a portfolio
    • Get a portfolio
    • Update a portfolio
    • Add a custom field to a portfolio
    • Add a portfolio item
    • Add users to a portfolio
    • Get portfolio items
    • Remove a custom field from a portfolio
    • Remove a portfolio item
    • Remove users from a portfolio
  • Custom Field Settings
    • Get a portfolio's custom fields
    • Get a project's custom fields
  • Project Memberships
    • Get a project membership
    • Get memberships from a project
  • Project Statuses
    • Delete a project status
    • Get a project status
    • Get statuses from a project
    • Create a project status
  • Projects
    • Get multiple projects
    • Create a project
    • Delete a project
    • Get a project
    • Update a project
    • Add a custom field to a project
    • Add followers to a project
    • Add users to a project
    • Duplicate a project
    • Remove a custom field from a project
    • Remove followers from a project
    • Remove users from a project
    • Get task count of a project
    • Get projects a task is in
    • Get a team's projects
    • Create a project in a team
    • Get all projects in a workspace
    • Create a project in a workspace
  • Sections
    • Get sections in a project
    • Create a section in a project
    • Move or Insert sections
    • Delete a section
    • Get a section
    • Update a section
    • Add task to section
  • Tasks
    • Get tasks from a project
    • Get tasks from a section
    • Get tasks from a tag
    • Get multiple tasks
    • Create a task
    • Delete a task
    • Get a task
    • Update a task
    • Set dependencies for a task
    • Set dependents for a task
    • Add followers to a task
    • Add a project to a task
    • Add a tag to a task
    • Get dependencies from a task
    • Get dependents from a task
    • Duplicate a task
    • Unlink dependencies from a task
    • Unlink dependents from a task
    • Remove followers from a task
    • Remove a project from a task
    • Remove a tag from a task
    • Set the parent of a task
    • Get subtasks from a task
    • Create a subtask
    • Get tasks from a user task list
    • Search tasks in a workspace
  • Stories
    • Delete a story
    • Get a story
    • Update a story
    • Get stories from a task
    • Create a story on a task
  • Tags
    • Get multiple tags
    • Create a tag
    • Delete a tag
    • Get a tag
    • Update a tag
    • Get a task's tags
    • Get tags in a workspace
    • Create a tag in a workspace
  • Team Memberships
    • Get team memberships
    • Get a team membership
    • Get memberships from a team
    • Get memberships from a user
  • Users
    • Get users in a team
    • Get multiple users
    • Get a user
    • Get a user's favorites
    • Get users in a workspace or organization
  • Time Periods
    • Get time periods
    • Get a time period
  • User Task Lists
    • Get a user task list
    • Get a user's task list
  • Workspace Memberships
    • Get workspace memberships for a user
    • Get a workspace membership
    • Get the workspace memberships for a workspace
  • Webhooks
    • Get multiple webhooks
    • Establish a webhook
    • Delete a webhook
    • Get a webhook
  • Workspaces
    • Get multiple workspaces
    • Get a workspace
    • Update a workspace
    • Add a user to a workspace or organization
    • Remove a user from a workspace or organization
  • Typeahead
    • Get objects via typeahead
  1. Custom Fields

Update a custom field

PUT
/custom_fields/{custom_field_gid}
Custom Fields
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.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PUT 'https://app.asana.com/api/1.0/custom_fields/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "enabled": true,
        "enum_options": [
            {
                "color": "blue",
                "enabled": true,
                "name": "Low"
            }
        ],
        "name": "Status",
        "number_value": 5.2,
        "resource_subtype": "text",
        "text_value": "Some Value",
        "currency_code": "EUR",
        "custom_label": "gold pieces",
        "custom_label_position": "suffix",
        "description": "Development team priority",
        "format": "custom",
        "has_notifications_enabled": true,
        "precision": 2,
        "workspace": "1331"
    }
}'
Response Response Example
200 - Example 1
{
  "data": {
    "gid": "12345",
    "resource_type": "task",
    "display_value": "blue",
    "enabled": true,
    "enum_options": [
      {
        "gid": "12345",
        "resource_type": "task",
        "color": "blue",
        "enabled": true,
        "name": "Low"
      }
    ],
    "name": "Status",
    "number_value": 5.2,
    "resource_subtype": "text",
    "text_value": "Some Value",
    "type": "text",
    "currency_code": "EUR",
    "custom_label": "gold pieces",
    "custom_label_position": "suffix",
    "description": "Development team priority",
    "format": "custom",
    "has_notifications_enabled": true,
    "is_global_to_workspace": true,
    "precision": 2,
    "created_by": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    },
    "enum_value": {
      "gid": "12345",
      "resource_type": "task",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    },
    "multi_enum_values": [
      {
        "gid": "12345",
        "resource_type": "task",
        "color": "blue",
        "enabled": true,
        "name": "Low"
      }
    ]
  }
}

Request

Path Params
custom_field_gid
string 
required
Body Params application/json
data
object (CustomFieldRequest) 
optional
Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the Custom Fields developer documentation for more information about how custom fields relate to various resources in Asana.
Users in Asana can lock custom fields, which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code 403 Forbidden.
workspace
string 
required
Create-Only The workspace to create a custom field in.
Example:
1331
currency_code
string  | null 
optional
ISO 4217 currency code to format this custom field. This will be null if the format is not currency.
Example:
EUR
custom_label
string  | null 
optional
This is the string that appears next to the custom field value. This will be null if the format is not custom.
Example:
gold pieces
custom_label_position
enum<string> 
optional
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.
Allowed values:
prefixsuffix
Example:
suffix
description
string 
optional
Opt In. The description of the custom field.
Example:
Development team priority
enum_options
array[object (EnumOption) {3}] 
optional
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.
format
enum<string> 
optional
The format of this custom field.
Allowed values:
currencyidentifierpercentagecustomnone
Example:
custom
has_notifications_enabled
boolean 
optional
Conditional. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.
Example:
true
precision
integer 
optional
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.
Example:
2
enabled
boolean 
optional
Conditional. Determines if the custom field is enabled or not.
Example:
true
name
string 
optional
The name of the custom field.
Example:
Status
number_value
number 
optional
Conditional. This number is the value of a number custom field.
Example:
5.2
resource_subtype
enum<string> 
optional
The type of the custom field. Must be one of the given values.
Allowed values:
textenummulti_enumnumber
Example:
text
text_value
string 
optional
Conditional. This string is the value of a text custom field.
Example:
Some Value
Examples

Responses

🟢200The custom field was successfully updated.
application/json
Body
data
object (CustomFieldResponse) 
optional
Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the Custom Fields developer documentation for more information about how custom fields relate to various resources in Asana.
Users in Asana can lock custom fields, which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code 403 Forbidden.
created_by
object 
UserCompact
optional
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
enum_value
object 
optional
Conditional. Only relevant for custom fields of type enum. This object is the chosen value of an enum custom field.
multi_enum_values
array[object (EnumOption) {5}] 
optional
Conditional. Only relevant for custom fields of type multi_enum. This object is the chosen values of a multi_enum custom field.
currency_code
string  | null 
optional
ISO 4217 currency code to format this custom field. This will be null if the format is not currency.
Example:
EUR
custom_label
string  | null 
optional
This is the string that appears next to the custom field value. This will be null if the format is not custom.
Example:
gold pieces
custom_label_position
enum<string> 
optional
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.
Allowed values:
prefixsuffix
Example:
suffix
description
string 
optional
Opt In. The description of the custom field.
Example:
Development team priority
enum_options
array[object (EnumOption) {5}] 
optional
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.
format
enum<string> 
optional
The format of this custom field.
Allowed values:
currencyidentifierpercentagecustomnone
Example:
custom
has_notifications_enabled
boolean 
optional
Conditional. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.
Example:
true
is_global_to_workspace
boolean 
read-onlyoptional
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.
Example:
true
precision
integer 
optional
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.
Example:
2
gid
string 
read-onlyoptional
Globally unique identifier of the resource, as a string.
Example:
12345
resource_type
string 
read-onlyoptional
The base type of this resource.
Example:
task
display_value
string 
read-onlyoptional
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:
blue
enabled
boolean 
optional
Conditional. Determines if the custom field is enabled or not.
Example:
true
name
string 
optional
The name of the custom field.
Example:
Status
number_value
number 
optional
Conditional. This number is the value of a number custom field.
Example:
5.2
resource_subtype
enum<string> 
optional
The type of the custom field. Must be one of the given values.
Allowed values:
textenummulti_enumnumber
Example:
text
text_value
string 
optional
Conditional. This string is the value of a text custom field.
Example:
Some Value
type
enum<string> 
read-onlyoptional
Deprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values.
Allowed values:
textenummulti_enumnumber
🟠400400
🟠401401
🟠403403
🟠404404
🔴500500
Modified at 2022-09-13 02:00:31
Previous
Get a custom field
Next
Create an enum option
Built with