[New] Rich text support for text custom fields

Asana Community API & Developers Changelog
,
1

Summary

  • Text-type custom fields now support rich text content (bold, italic, underline, links, etc.) through the API.

  • A new html_text_value response field surfaces the rich text HTML content of text custom fields on read endpoints.

  • A new html_custom_fields request parameter allows writing rich text content to text custom fields on create and update endpoints.

  • This brings the API to feature parity with the application, where rich text editing for text custom fields is already available.

Who is affected

  • No breaking changes. Existing integrations will continue to work without modification.

  • Developers who currently read text_value or write via custom_fields will see no change in behavior: plain text remains the default.

  • Developers who want to leverage rich text formatting in text custom fields can opt in to reading and writing HTML content.

Key behaviors

  • Writing via html_custom_fields automatically updates the plain text text_value with the plain text equivalent (HTML stripped), and vice versa; the two fields always stay in sync.

  • Writing via custom_fields treats values as plain text; the content is escaped and sanitized, and the rich text html_text_value is updated accordingly.

  • The display_value for text-type custom fields is always derived from the plain text value.

  • Rich text values must be wrapped in <body></body> tags, consistent with existing rich text conventions.

Timeline

This is a non-breaking, additive change. Rich text support for text custom fields is available now across all affected endpoints.

Usage

Reading rich text

Full response endpoints (rich text returned by default)

Method Route
GET /tasks/{task_gid}
GET /workspaces/{workspace_gid}/tasks/custom_id/{custom_id}

The html_text_value field is included automatically on each custom field object in the response:

GET /tasks/{task_gid}


{

  "gid": "12345",

  "resource_type": "custom_field",

  "resource_subtype": "text",

  "name": "Release Notes",

  "text_value": "Hello world",

  "html_text_value": "<body><strong>Hello</strong> world</body>",

  "display_value": "Hello world"

}

Opt-in endpoints (rich text via opt_fields)

For all other read endpoints, including tasks listed by project/section/tag, projects, goals, and portfolios: include custom_fields.html_text_value in opt_fields:

GET /projects/99999?
opt_fields=custom_fields.name,custom_fields.text_value,custom_fields.html_text_value


{

  "data": {

    "gid": "99999",

    "custom_fields": [

           {
      
              "gid": "12345",
      
              "name": "Release Notes",
      
              "text_value": "hello world",
      
              "html_text_value": "<body><strong>hello</strong> world</body>"
      
           }

      ]
  
    }

}

This follows the same opt-in pattern used for other rich text fields like html_notes on tasks.

Writing rich text

Use the new html_custom_fields request parameter on create and update endpoints. It works identically to custom_fields, but values are interpreted as rich text HTML:

PUT /tasks/12345

{

  "data": {

    "html_custom_fields": {

      "11111": "<body><strong>Hello</strong> world</body>"

    }

  }

}

Supported write endpoints

Method Route
POST /tasks
POST /tasks/{task_gid}/subtasks
POST /projects
POST /teams/{team_gid}/projects
POST /workspaces/{workspace_gid}/projects
PUT /tasks/{task_gid}
PUT /projects/{project_gid}
PUT /portfolios/{portfolio_gid}
PUT /goals/{goal_gid}

Error codes

Status Message
400 Bad Request Rich text custom field value must be wrapped in
400 Bad Request Unable to parse rich text HTML. The value contains invalid or unsupported HTML elements.
400 Bad Request Rich text HTML contains an unsupported attribute on an anchor tag.
400 Bad Request Custom field {GID} does not support rich text content.

Resources

Questions and Feedback

If you have questions or feedback about rich text support for custom fields, please reply to this post.

4 Likes