The Asana Custom Fields API allows developers to create and manage custom fields within Asana, a popular project management tool. With this API, users can define custom fields that are specific to their organization's needs, such as tracking budgets, deadlines, or project statuses. These custom fields can be added to tasks, projects, and portfolios within Asana, providing users with greater flexibility and control over their project data.
openapi: 3.1.0
info:
title: Asana Custom Fields API
description: >-
The Asana Custom Fields API allows developers to create and manage custom
fields within Asana. Custom fields provide extra information on tasks,
projects, and portfolios with types including text, number, enum,
multi_enum, date, and people.
version: '1.0'
termsOfService: https://asana.com/terms
contact:
name: Asana Support
url: https://asana.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://app.asana.com/api/1.0
description: Main endpoint.
security:
- personalAccessToken: []
- oauth2: []
tags:
- name: Custom Fields
description: Manage custom field metadata and values.
paths:
/custom_fields:
post:
summary: Asana Create a custom field
description: Creates a new custom field in a workspace.
operationId: createCustomField
tags:
- Custom Fields
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomFieldRequest'
responses:
'201':
description: Successfully created a custom field.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomFieldResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'500':
description: Internal server error.
/custom_fields/{custom_field_gid}:
get:
summary: Asana Get a custom field
description: Returns the complete definition of a custom field.
operationId: getCustomField
tags:
- Custom Fields
parameters:
- name: custom_field_gid
in: path
required: true
description: Globally unique identifier for the custom field.
schema:
type: string
example: '12345'
responses:
'200':
description: Successfully retrieved the complete definition of a custom field.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomFieldResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
put:
summary: Asana Update a custom field
description: Updates an existing custom field.
operationId: updateCustomField
tags:
- Custom Fields
parameters:
- name: custom_field_gid
in: path
required: true
schema:
type: string
example: '12345'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomFieldRequest'
responses:
'200':
description: Successfully updated the custom field.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomFieldResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
delete:
summary: Asana Delete a custom field
description: Deletes a specific, existing custom field.
operationId: deleteCustomField
tags:
- Custom Fields
parameters:
- name: custom_field_gid
in: path
required: true
schema:
type: string
example: '12345'
responses:
'200':
description: Successfully deleted the custom field.
content:
application/json:
schema:
type: object
properties:
data:
type: object
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/workspaces/{workspace_gid}/custom_fields:
get:
summary: Asana Get a workspace's custom fields
description: Returns a list of the compact representation of all custom fields in a workspace.
operationId: getCustomFieldsForWorkspace
tags:
- Custom Fields
parameters:
- name: workspace_gid
in: path
required: true
schema:
type: string
example: '12345'
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
- name: offset
in: query
required: false
schema:
type: string
responses:
'200':
description: Successfully retrieved all custom fields for the workspace.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomFieldCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
components:
securitySchemes:
personalAccessToken:
type: http
scheme: bearer
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.asana.com/-/oauth_authorize
tokenUrl: https://app.asana.com/-/oauth_token
scopes:
default: Provides access to all endpoints documented in the API reference.
schemas:
CustomFieldCompact:
type: object
properties:
gid:
type: string
readOnly: true
example: '12345'
resource_type:
type: string
readOnly: true
example: custom_field
name:
type: string
example: Priority
resource_subtype:
type: string
enum:
- text
- enum
- multi_enum
- number
- date
- people
example: enum
type:
type: string
enum:
- text
- enum
- multi_enum
- number
- date
- people
CustomFieldRequest:
type: object
properties:
name:
type: string
example: Priority
resource_subtype:
type: string
enum:
- text
- enum
- multi_enum
- number
- date
- people
description:
type: string
workspace:
type: string
example: '12345'
precision:
type: integer
description: Only relevant for custom fields of type number.
enum_options:
type: array
items:
type: object
properties:
name:
type: string
color:
type: string
enabled:
type: boolean
CustomFieldResponse:
type: object
properties:
gid:
type: string
readOnly: true
example: '12345'
resource_type:
type: string
readOnly: true
example: custom_field
name:
type: string
example: Priority
resource_subtype:
type: string
enum:
- text
- enum
- multi_enum
- number
- date
- people
description:
type: string
type:
type: string
display_value:
type: string
readOnly: true
precision:
type: integer
enum_options:
type: array
items:
type: object
properties:
gid:
type: string
name:
type: string
enabled:
type: boolean
color:
type: string
created_by:
type: object
properties:
gid:
type: string
name:
type: string
resource_type:
type: string