Custom Field Settings

Custom fields are applied to a particular project or portfolio with the Custom Field Settings resource. This resource both represents the many-to-many join of the Custom Field and Project or Portfolio as well as stores information that is relevant to that particular pairing; for instance, the is_important property determines some possible application-specific handling of that custom field and parent.

Custom Field Settings have the following fields:
Field Description
id 1234 Read-only. Globally unique ID of the custom field settings object. Note: This field is under active migration to the gid field—please see our blog post for more information.
gid "1234" Read-only. Globally unique ID of the custom field settings object.
resource_type "custom_field_setting" Read-only. The resource type of this resource. The value for this resource is always custom_field_setting
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this custom field setting was created.
is_important false Read-only. is_important is used in the Asana web application to determine if this custom field is displayed in the task list (left pane) of a project. A project can have a maximum of 5 custom field settings marked as is_important.
parent {id: 29485, gid: "29485", name: "Marketing steps", resource_type: "project"} {id: 36985, gid: "36985", name: "Product launch", resource_type: "portfolio"} The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.
project { id: 1234, gid: "1234", name: 'Bugs' } Read-only. Deprecated: new integrations should prefer the parent field. The id of the project that this custom field settings refers to.
custom_field { id: 1646, gid: "1646", name: 'Priority', type: 'enum' } Read-only. The custom field that is applied to the parent.

QUERY FOR CUSTOM FIELD SETTINGS ON A PROJECT

GET    /projects/{project_gid}/custom_field_settings

Returns a list of all of the custom fields settings on a project.

Parameter Description
project_gid "13579" Required: The ID of the project for which to list custom field settings
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/custom_field_settings

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 258147,
      "gid": "258147",
      "resource_type": "custom_field_setting",
      "custom_field": {
        "id": 124578,
        "gid": "124578",
        "resource_type": "custom_field",
        "resource_subtype": "enum",
        "name": "Priority",
        "type": "enum"
      },
      "is_important": false,
      "parent": {
        "id": 1331,
        "gid": "1331",
        "resource_type": "project",
        "name": "Things to buy"
      }
    },
    "~..."
  ]
}

QUERY FOR CUSTOM FIELD SETTINGS ON A PORTFOLIO

GET    /portfolios/{portfolio_gid}/custom_field_settings

Returns a list of all of the custom fields settings on a portfolio.

Parameter Description
portfolio_gid "36985" Required: The ID of the portfolio for which to list custom field settings
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/portfolios/36985/custom_field_settings

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 258147,
      "gid": "258147",
      "resource_type": "custom_field_setting",
      "custom_field": {
        "id": 124578,
        "gid": "124578",
        "resource_type": "custom_field",
        "resource_subtype": "enum",
        "name": "Priority",
        "type": "enum"
      },
      "is_important": true,
      "parent": {
        "id": 36985,
        "gid": "36985",
        "resource_type": "portfolio",
        "name": "Product launch"
      }
    },
    "~..."
  ]
}