[New/Upcoming] Reference Custom Fields

[John_Baldo]

Summary

Asana will soon support reference custom fields that store references to other Asana objects like tasks, projects, portfolios, and goals. This new custom field type allows you to create structured relationships between objects in your Asana workspace through the API.

Key benefits:

• Create structured relationships between Asana objects
• Configure which object types can be referenced per field
• Retrieve referenced objects with their names and resource types
• Build more connected workflows and reporting systems

Who is affected

If you read or make updates to custom field values over the API may see this new custom field type and may want to make changes to be able to handle references to other objects.

Timeline

• Late August 2025: Full public documentation and general release planned

Usage

Create / Update / Fetch Reference Custom Fields

• POST /custom_fields
• PUT /custom_fields/<gid>
• GET /custom_fields/<gid>

Field	Description
resource_subtype	Will now support reference
input_restrictions	Supported for resource custom field types, this array contains resource types that can be input into this reference custom field. Must be one of task / project / portfolio / goal.

// POST /custom_fields - Create a reference custom field
{
 "data": {
   "name": "Related Work",
   "description": "Reference to related projects or tasks",
   "resource_subtype": "reference",
   "input_restrictions": ["task", "project"],
   "workspace": "12345",
   "enabled": true,
   "is_global_to_workspace": true,
   "has_notifications_enabled": true
 }
}

Set Reference Custom Field Values

At launch, reference custom fields will be supported on tasks, projects, and portfolios.

• PUT /tasks/<gid>
• PUT /projects/<gid>
• PUT /portfolios/<gid>

// PUT /tasks/{task_gid} - Update reference custom field value on a task
{
 "data": {
   "custom_fields": {
     "1234567890123456": ["9876543210987654", "1111222233334444"],
     "5555666677778888": ["2222333344445555"]
   }
 }
}

Fetch Reference Custom Field Values

Reference custom task values may appear on GET endpoints for tasks, projects, and portfolios.

// GET /task/{gid}?opt_fields=custom_fields
// Task with reference custom field values
{
  "data": {
    "gid": "1234567890123456",
    "name": "Website Redesign Task",
    "custom_fields": [
      {
        "gid": "5555666677778888",
        "resource_type": "custom_field",
        "name": "Related Projects",
        "resource_subtype": "reference",
        "reference_value": [
          {
            "gid": "9876543210987654",
            "resource_type": "project",
            "name": "Q4 Marketing Campaign"
          },
          {
            "gid": "1111222233334444",
            "resource_type": "project", 
            "name": "Brand Guidelines Update"
          }
        ],
        "display_value": "Q4 Marketing Campaign, Brand Guidelines Update"
      },
      {
        "gid": "7777888899990000",
        "resource_type": "custom_field",
        "name": "Strategic Goal",
        "resource_subtype": "reference",
        "reference_value": [
          {
            "gid": "2222333344445555",
            "resource_type": "goal",
            "name": "Increase Brand Awareness"
          }
        ],
        "display_value": "Increase Brand Awareness"
      }
    ]
  }
}

Migration Steps

For new integrations:

• Use the new resource_subtype = “reference” when creating custom fields that need to store object references
• Configure input_restrictions to specify which object types can be referenced

For existing integrations:

• Consider gracefully handling reference custom field definitions and reference custom field values

Resources

• Custom Fields API Documentation
• Tasks API Documentation
• Projects API Documentation
• Portfolios API Documentation

Questions and Feedback

We’d love to hear how you plan to use reference custom fields in your integrations! Let us know if you have questions or feedback about this.

[lpb]

Nice, @John_Baldo!

Will this be in the product’s UX eventually? Any ballpark estimate if we don’t hold you to it?

Thanks,

Larry

[ka_nishiyama]

Hello, @John_Baldo .
A simple question: Can this be used with normal task editing (not via API)?

[John_Baldo]

Hi, this should be rolling out in the Asana web app and API at the same time in the post (late Aug). Giving advanced notice here so you can consider the new API data format.

Unfortunately, I can’t offer early access but I will do my best to reply here once it’s available!

[Phil_Seeman]

Thanks for that update, @John_Baldo.

[Mike_Hoefer]

Presuming this is the first step in making this an end user feature I’m pretty excited about it.

[Erjon_Metohu]

This is the best Asana news I have heard to date! Can’t wait for this to launch in the web app.

[FreshyJon]

Very much looking forward to this. Should help with our makeshift CRM setup within Asana, where a “Deal” task can then be referenced from the projects/portfolios that get created (and vice versa).

[Bobby_McGivney]

I’ve been excitedly checking on this one every day. Can’t wait!! Will this release to everyone in late August? or roll out over a certain amount of time?

[John_Baldo]

Great to see enthusiasm for this! Apologies, our release is delayed a bit. We’re planning to release next month in Sept. At least 2 weeks away. Will update here if you’d like to subscribe.

[Abraham_Kwan]

We’re super excited for this to release!

[Bobby_McGivney]

I see this has been officially announced!

Introducing Reference custom fields!

Exciting news! I don’t see it in my account yet. I tried logging out, clearing cookies, dusting off the ole desktop app - no luck. Are there any tricks to accessing this feature sooner than later, or is it just a waiting game? Hopefully it’s a quick rollout!

I personally don’t see it in my account yet, but I’ll be checking every few minutes until then Any tips there to fasttrack my access @John_Baldo ?

Thanks!

[John_Baldo]

Hi All, this should now be available! Thanks for your patience.

[Kryštof_Toman]

Hey, it would be amazing if this value could be used in Rules as input for certain actions.
When a task is closed and it has a referenced field, close all tasks from this field. Or similar actions.

Great addition btw looking forward to more features and QoL improvements

[lpb]

Welcome, @Kryštof_Toman,

See my post here and perhaps an uncoming reply there:

Introducing Reference custom fields!

@Emily_Roman, It doesn’t sound like this is yet supported in your fast follows from yesterday, right? Is it maybe anticipated in another set of fast follows?

Thanks,

Larry