Custom fields

Create a custom field

Changed on

<b>Required scope: </b><code>custom_fields:write</code>

Creates a new custom field in a workspace. Every custom field is required to be created in a specific workspace, and this workspace cannot be changed once set.

A custom field’s name must be unique within a workspace and not conflict with names of existing task properties such as Due Date or Assignee. A custom field’s type must be one of text, enum, multi_enum, number, date, or people.

Returns the full record of the newly created custom field.

post/custom_fields

Request

  • Base URL: https://app.asana.com/api/1.0
  • URL: https://app.asana.com/api/1.0/custom_fields
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.asana.com/-/oauth_authorize, token URL https://app.asana.com/-/oauth_token, scopes: custom_fields:write)

Query parameters

opt_fieldsstring[]

This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. Properties can include nested fields. To learn more, see the input/output options guide.

Request body

Example request

{
  "data": {
    "gid": "12345",
    "resource_type": "custom_field",
    "name": "Status",
    "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"
    ],
    "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",
    "workspace": "1331",
    "people_value": [
      "12345"
    ],
    "reference_value": [
      "12345"
    ],
    "resource_subtype": "text"
  }
}

Response

Custom field successfully created.

Example response

{
  "data": {
    "gid": "12345",
    "resource_type": "custom_field",
    "name": "Status",
    "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"
    ],
    "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",
    "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"
  }
}

Changes

  • b3dcd9ce0bf2Revision changes
    • breaking

      request property ////////////// was restricted to a list of enum values

    • warning

      added the new goal enum value to the ////////// response property for the response status

    • warning

      added the new goal enum value to the /// response property for the response status

    • warning

      added the new portfolio enum value to the ////////// response property for the response status

    • warning

      added the new portfolio enum value to the /// response property for the response status

    • warning

      added the new project enum value to the ////////// response property for the response status

    • warning

      added the new project enum value to the /// response property for the response status

    • warning

      added the new reference enum value to the ///////// response property for the response status

    • warning

      added the new reference enum value to the ///////// response property for the response status

    • warning

      added the new task enum value to the ////////// response property for the response status

    • warning

      added the new task enum value to the /// response property for the response status

    • info

      added the new goal enum value to the request property //////////////

    • info

      added the new portfolio enum value to the request property //////////////

    • info

      added the new project enum value to the request property //////////////

    • info

      added the new reference enum value to the request property /////////////

    • info

      added the new reference enum value to the request property /////////////

    • info

      added the new task enum value to the request property //////////////

  • b04e9dcf7c00Revision changes
    • info

      added the enum value html_text_value to the property items/ of the query request parameter opt_fields

    • info

      added the optional property // to the response with the status