Custom Fields

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.

Custom Fields have the following fields:

Field Description
id 1234 Read-only. Globally unique ID of the custom field.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this custom field was created.
name 'Priority' Read-only. The name of the custom field.
type 'text' 'enum' 'number' Read-only. The type of the custom field. Must be one of the given values.
enum_options [ { id: 789, name: 'Low', enabled: 'true', color: 'blue' }, ... ] Read-only. Only relevant for custom fields of type ‘Enum’. This array specifies the possible values which an enum custom field can adopt.
precision 2 Read-only. 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.

TYPE-SPECIFIC CUSTOM FIELD INFORMATION

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.

Get the metadata for a custom field of type ‘text’

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/custom_fields/124578

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 134679,
      "created_at": "2016-07-11T14:29:23.249Z",
      "name": "Owner",
      "type": "text"
    }
  ]
}

Get the metadata for a custom field of type ‘number’

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/custom_fields/124578

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 938271,
      "created_at": "2016-07-11T14:29:23.249Z",
      "name": "Price",
      "type": "number",
      "precision": 2
    }
  ]
}

Get the metadata for a custom field when that field is of type ‘enum’.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/custom_fields/124578

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 124578,
      "created_at": "2016-07-11T14:29:23.249Z",
      "name": "Priority",
      "type": "enum",
      "enum_options": [
        {
          "id": 789,
          "name": "Low",
          "enabled": true,
          "color": "blue"
        },
        {
          "id": 208,
          "name": "Medium",
          "enabled": false,
          "color": "yellow"
        },
        {
          "id": 439,
          "name": "High",
          "enabled": true,
          "color": "red"
        }
      ]
    }
  ]
}

GET A CUSTOM FIELD

GET    /custom_fields/custom-field-id

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

Parameter Description
custom-field 124578 Required: Globally unique identifier for the custom field.

QUERY FOR CUSTOM FIELDS

GET    /workspaces/workspace-id/custom_fields

Returns a list of the compact representation of all of the custom fields in a workspace.

Parameter Description
workspace 1331 Required: The workspace or organization to find custom field definitions in.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/workspaces/14916/custom_fields

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 124578,
      "name": "Priority",
      "type": "enum"
    },
    {
      "id": 134679,
      "name": "Owner",
      "type": "text"
    },
    "~..."
  ]
}