[New] Custom fields on goals

English Forum Developers & API Changelog
,
1

Summary

Goals can now include custom fields through the Asana API, bringing the same powerful metadata capabilities that are available for projects and portfolios to your goal management workflows.

Custom fields on goals support most field types including text, number, enum (single-select), multi-enum (multi-select), date, and people fields.

Why we’re making this change

This change benefits developers building integrations that work with goal management and reporting:

  • Goal tracking applications - Can now capture and display additional metadata about goals beyond the basic name, description, and progress
  • Reporting and analytics tools - Can group, filter, and analyze goals based on custom field values (e.g., by department, priority, or business area)

Usage

Reading Custom Field Values on Goals

All goal endpoints now support returning custom field data using the opt_fields parameter. Unlike other objects like tasks, you’ll need to explicitly request custom field data as optional fields. This is to make the API more performant by default.

New optional fields

Parameter Description
custom_fields Object mapping custom field GIDs to values
custom_field_settings Available when using opt_fields to show configured fields

List custom field values and custom field settings

// GET /goals/1234567890123456?opt_fields=name,custom_fields,custom_field_settings

{
  "data": {
    "gid": "1234567890123456",
    "name": "Increase user engagement",
    "custom_fields": [
      {
        "gid": "987654321098765",
        "name": "Priority",
        "type": "enum",
        "enum_value": {
          "gid": "123456789012345",
          "name": "High",
          "color": "red"
        }
      }
    ],
    "custom_field_settings": [
      {
        "gid": "555666777888999",
        "custom_field": {
          "gid": "987654321098765",
          "name": "Priority"
        }
      }
    ]
  }
}

Updating Goals with Custom Fields

When updating goals, include custom field values in the request. Here is an example of assigning a custom field value to a goal.

// PUT /goals/12345
{
  "data": {
    "custom_fields": {
      "987654321098765": "456789012345678"
    }
  }
}

Managing Custom Field Settings

New endpoints for managing which custom fields are available on goals:

Add Custom Field Setting

// POST /goals/1234567890123456/addCustomFieldSetting
{
  "data": {
    "custom_field": "987654321098765"
  }
}

Remove Custom Field Setting

// POST /goals/1234567890123456/removeCustomFieldSetting
{
  "data": {
    "custom_field": "987654321098765"
  }
}

List Custom Field Settings

// GET /goals/1234567890123456/custom_field_settings

{
  "data": [
    {
      "gid": "9876543210987654",
      "resource_type": "custom_field_setting",
      "parent": {
        "gid": "1234567890123456",
        "name": "Q1 Revenue Growth",
        "resource_type": "goal"
      },
      "is_important": true,
      "custom_field": {
        "gid": "1111222233334444",
        "name": "Progress Percentage",
        "resource_type": "custom_field",
        "type": "number",
        "precision": 0
      }
    },
    {
      "gid": "1357924680135792",
      "resource_type": "custom_field_setting",
      "parent": {
        "gid": "1234567890123456",
        "name": "Q1 Revenue Growth",
        "resource_type": "goal"
      },
      "is_important": false,
      "custom_field": {
        "gid": "2468135792468135",
        "name": "Department",
        "resource_type": "custom_field",
        "type": "text"
      }
    },
    {
      "gid": "8642097531864209",
      "resource_type": "custom_field_setting", 
      "parent": {
        "gid": "1234567890123456",
        "name": "Q1 Revenue Growth",
        "resource_type": "goal"
      },
      "is_important": true,
      "custom_field": {
        "gid": "7531842609753184",
        "name": "Target Date",
        "resource_type": "custom_field",
        "type": "date"
      }
    }
  ]
}

Timeline

This is now available!

Note: Custom fields functionality requires appropriate workspace permissions and may have plan-level restrictions.

Resources

Questions and Feedback

We’d love to hear how you plan to use custom fields on goals in your integrations. Share your feedback and use cases in the comments below.

2 Likes