[New] Read and update custom fields on Users

English Forum Developers & API Changelog
, , ,
1

Summary

We’re introducing API support for custom fields on users, allowing developers to programmatically read and update user custom field values, as well as retrieve team custom field settings. This enhancement enables seamless synchronization of people data from external HR systems directly into Asana.

With these new endpoints, you can now sync employee attributes like location, start date, department, manager, cost center, and other organizational data directly through the API. This eliminates the need for manual CSV imports and provides a scalable solution for keeping user data up to date.

Who is affected

This feature benefits developers building integrations that need to:

  • Sync HR system data with Asana user profiles
  • Maintain up-to-date employee information across systems

Note: Custom fields on users are only available in Asana’s new paid tiers. Organizations on legacy or free tiers will not have access to this functionality.

Timeline

These API endpoints are now available for general use. No migration is required as these are new capabilities that don’t affect existing functionality.

Usage

Setting up custom fields on users

Before using the API, create custom fields within a team through the Asana UI (setup guide). All team members will inherit the team’s custom fields, similar to how tasks inherit custom fields from their projects.

For organization-wide fields like “Location” or “Employee ID”, we recommend creating a “Staff” team containing all users. You can efficiently add users using CSV import or SCIM provisioning.

New API endpoints

1. Read a single user with custom fields

Endpoints:

  • GET /users/{user_gid}
  • GET /workspaces/{workspace_gid}/users/{user_gid}
# Get user with custom fields
GET /users/1234567890?opt_fields=name,email,custom_fields&workspace=9876543210

Response:

// GET /users/1234567890?opt_fields=custom_fields,custom_fields.display_value,custom_fields.type,custom_fields.enum_value,custom_fields.text_value,custom_fields.people_value&workspace=9876543210
{
  "data": {
    "gid": "1234567890",
    "resource_type": "user",
    "name": "Sarah Chen",
    "email": "sarah.chen@company.com",
    "custom_fields": [
      {
        "gid": "1208403004301899",
        "resource_type": "custom_field",
        "name": "Department",
        "type": "enum",
        "display_value": "Engineering",
        "enum_value": {
          "gid": "1208403004301900",
          "resource_type": "enum_option",
          "name": "Engineering"
        }
      },
      {
        "gid": "1209706348303736",
        "resource_type": "custom_field",
        "name": "Location",
        "type": "text",
        "display_value": "San Francisco, CA",
        "text_value": "San Francisco, CA"
      },
      {
        "gid": "1211038924894266",
        "resource_type": "custom_field",
        "name": "Manager",
        "type": "people",
        "display_value": "manager@company.com",
        "people_value": [
          {
            "gid": "9876543210",
            "resource_type": "user",
            "name": "Alex Manager"
          }
        ]
      }
    ]
  }
}

2. Bulk read users with custom fields

Endpoints:

  • GET /users/
  • GET /teams/{team_gid}/users
# Get all users in a workspace with custom fields
GET /users?workspace=9876543210&opt_fields=name,email,custom_fields

3. Update a user’s custom field values

Endpoint:

  • PUT /users/{user_gid}
  • PUT /workspaces/{workspace_gid}/users/{user_gid}
# Update user custom fields
PUT /users/1234567890?workspace=9876543210
Content-Type: application/json

{
  "data": {
    "custom_fields": {
      "1209706348303736": "Austin, TX",
      "1208403004301899": "1208403004301901"
    }
  }
}

4. Read team custom field settings

Endpoints:

  • GET /teams
  • GET /teams/{team_gid}
  • GET /teams/{team_gid}/custom_field_settings
# Get team custom field settings
GET /teams/9876543210/custom_field_settings

Response:

{
  "data": [
    {
      "gid": "1208403004301899",
      "resource_type": "custom_field_setting",
      "custom_field": {
        "gid": "1208403004301899", 
        "name": "Department",
        "type": "enum",
        "enum_options": [
          {
            "gid": "1208403004301900",
            "name": "Engineering",
            "enabled": true,
            "color": "blue"
          }
        ]
      },
      "is_important": true
    }
  ]
}

Custom field value formats

Custom field values follow the same format as task, project, and portfolio custom fields:

Field Type Value Format Example
text String "San Francisco, CA"
number Number 75000
enum Enum option GID "1208403004301900"
people User email "manager@company.com"
date Date object {"date": "2024-01-15"}

Resources

Questions and Feedback

Our team is monitoring this topic. Please share your feedback, report any issues, and ask questions—your input helps us refine and improve the developer experience with this new capability.

2 Likes
2

Hi, I’ve been testing custom fields on Users, and have a few questions about it.

  • Can User custom field be created by API?
    • If it’s not available, will Asana team planning to launch this API?
  • How to distinguish between normal custom fields and User custom fields?
    • When I tried “GET a team” - check one of the User custom field GID - “GET a custom field” - in the response, there was no such separator.
    • As you know, both of them are called “custom field”, but it’s quite diffrent when we use it in Asana UI
      • for instance, I can’t leverage normal custom fields as a field in team member list, and neither in vice versa (in projects or portfolios)
      • so I was wondering how I can distinguish them in queries?