Create a custom field

POST

/custom_fields

Custom Fields

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’, or ‘number’.

Returns the full record of the newly created custom field.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '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 Example

201 - 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

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:

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

🟢201Custom field successfully created.

application/json

Body

data

object (CustomFieldResponse)

optional

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

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

Example:

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

Submit parallel requests

Delete a custom field