Asana API
Getting access, Developing, Testing
Back to Asana
Create A Goal
Creates a new goal in a workspace or team.
Returns the full record of the newly created goal.
Input
type: object
properties:
parameters:
type: object
properties:
opt_pretty:
type: boolean
description: >-
Provides “pretty” output.
Provides the response in a “pretty” format. In the case of JSON this
means doing proper line breaking and indentation to make it readable.
This will take extra time and increase the response size so it is
advisable only to use this during debugging.
opt_fields:
type: array
items:
type: string
description: >-
Defines fields to return.
Some requests return *compact* representations of objects in order to
conserve resources and complete the request more efficiently. Other
times requests return more information than you may need. This option
allows you to list the exact set of fields that the API should be sure
to return for the objects. The field names should be provided as
paths, described below.
The id of included objects will always be returned, regardless of the
field options.
limit:
type: integer
description: >-
Results per page.
The number of objects to return per page. The value must be between 1
and 100.
offset:
type: string
description: >-
Offset token.
An offset to the next page returned by the API. A pagination request
will return an offset token, which can be used as an input parameter
to the next request. If an offset is not passed in, the API will
return the first page of results.
'Note: You can only pass in an offset that was returned to you via a
previously paginated request.'
title: Parameters
data:
type: object
properties:
data:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: The name of the goal.
example: Grow web traffic by 30%
html_notes:
type: string
description: The notes of the goal with formatting as HTML.
example: <body>Start building brand awareness.</body>
notes:
type: string
description: >-
Free-form textual information associated with the goal (i.e. its
description).
example: Start building brand awareness.
due_on:
type: string
description: >-
The localized day on which this goal is due. This takes a date
with format `YYYY-MM-DD`.
example: '2019-09-15T00:00:00.000Z'
nullable: true
start_on:
type: string
description: >-
The day on which work for this goal begins, or null if the goal
has no start date. This takes a date with `YYYY-MM-DD` format, and
cannot be set unless there is an accompanying due date.
example: '2019-09-14T00:00:00.000Z'
nullable: true
status:
type: string
description: >-
The current status of this goal. When the goal is open, its status
can be `green`, `yellow`, and `red` to reflect "On Track", "At
Risk", and "Off Track", respectively. When the goal is closed, the
value can be `missed`, `achieved`, `partial`, or `dropped`.
*Note* you can only write to this property if `metric` is set.
example: green
nullable: true
is_workspace_level:
type: boolean
description: >-
*Conditional*. This property is only present when the `workspace`
provided is an organization. Whether the goal belongs to the
`workspace` (and is listed as part of the workspace’s goals) or
not. If it isn’t a workspace-level goal, it is a team-level goal,
and is associated with the goal’s team.
example: true
liked:
type: boolean
description: True if the goal is liked by the authorized user, false if not.
example: false
team:
type: string
description: >-
*Conditional*. This property is only present when the `workspace`
provided is an organization.
example: '12345'
nullable: true
workspace:
type: string
description: The `gid` of a workspace.
example: '12345'
followers:
type: array
items:
type: string
time_period:
type: string
description: The `gid` of a time period.
example: '12345'
nullable: true
owner:
type: string
description: The `gid` of a user.
example: '12345'
nullable: true
title: Data
Output
type: object
properties:
data:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: The name of the goal.
example: Grow web traffic by 30%
html_notes:
type: string
description: The notes of the goal with formatting as HTML.
example: <body>Start building brand awareness.</body>
notes:
type: string
description: >-
Free-form textual information associated with the goal (i.e. its
description).
example: Start building brand awareness.
due_on:
type: string
description: >-
The localized day on which this goal is due. This takes a date with
format `YYYY-MM-DD`.
example: '2019-09-15T00:00:00.000Z'
nullable: true
start_on:
type: string
description: >-
The day on which work for this goal begins, or null if the goal has no
start date. This takes a date with `YYYY-MM-DD` format, and cannot be
set unless there is an accompanying due date.
example: '2019-09-14T00:00:00.000Z'
nullable: true
status:
type: string
description: >-
The current status of this goal. When the goal is open, its status can
be `green`, `yellow`, and `red` to reflect "On Track", "At Risk", and
"Off Track", respectively. When the goal is closed, the value can be
`missed`, `achieved`, `partial`, or `dropped`.
*Note* you can only write to this property if `metric` is set.
example: green
nullable: true
is_workspace_level:
type: boolean
description: >-
*Conditional*. This property is only present when the `workspace`
provided is an organization. Whether the goal belongs to the
`workspace` (and is listed as part of the workspace’s goals) or not.
If it isn’t a workspace-level goal, it is a team-level goal, and is
associated with the goal’s team.
example: true
liked:
type: boolean
description: True if the goal is liked by the authorized user, false if not.
example: false
likes:
description: Array of likes for users who have liked this goal.
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the object, as a string.
type: string
readOnly: true
example: '12345'
user:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: >-
*Read-only except when same user as requester*. The user’s
name.
example: Greg Sanchez
num_likes:
description: The number of users who have liked this goal.
type: integer
readOnly: true
example: 5
team:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the team.
type: string
example: Marketing
workspace:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the workspace.
type: string
example: My Company Workspace
followers:
type: array
description: Array of users who are members of this goal.
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
time_period:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
end_on:
type: string
description: The localized end date of the time period in `YYYY-MM-DD` format.
example: '2019-09-14T00:00:00.000Z'
start_on:
type: string
description: >-
The localized start date of the time period in `YYYY-MM-DD`
format.
example: '2019-09-13T00:00:00.000Z'
period:
type: string
description: >-
The cadence and index of the time period. The value is one of:
`FY`, `H1`, `H2`, `Q1`, `Q2`, `Q3`, or `Q4`.
enum:
- FY
- H1
- H2
- Q1
- Q2
- Q3
- Q4
example: Q1
display_name:
type: string
description: A string representing the cadence code and the fiscal year.
example: Q1 FY22
metric:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
resource_subtype:
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
type: string
readOnly: true
example: number
enum:
- number
precision:
description: >-
*Conditional*. Only relevant for goal metrics of type ‘Number’.
This field dictates the number of places after the decimal to
round to, i.e. 0 is integer values, 1 rounds to the nearest tenth,
and so on. Must be between 0 and 6, inclusive.
For percentage format, this may be unintuitive, as a value of 0.25
has a precision of 0, while a value of 0.251 has a precision of 1.
This is due to 0.25 being displayed as 25%.
type: integer
example: 2
unit:
description: A supported unit of measure for the goal metric, or none.
type: string
enum:
- none
- currency
- percentage
currency_code:
description: >-
ISO 4217 currency code to format this custom field. This will be
null if the `unit` is not `currency`.
type: string
nullable: true
example: EUR
initial_number_value:
description: This number is the start value of a goal metric of type number.
type: number
example: 5.2
target_number_value:
description: >-
This number is the end value of a goal metric of type number. This
number cannot equal `initial_number_value`.
type: number
example: 10.2
current_number_value:
description: This number is the current value of a goal metric of type number.
type: number
example: 8.12
current_display_value:
description: This string is the current value of a goal metric of type string.
type: string
readOnly: true
example: '8.12'
progress_source:
description: >-
This field defines how the progress value of a goal metric is
being calculated. A goal's progress can be provided manually by
the user, calculated automatically from contributing subgoals or
projects, or managed by an integration with an external data
source, such as Salesforce.
type: string
enum:
- manual
- subgoal_progress
- project_task_completion
- project_milestone_completion
- external
example: manual
can_manage:
description: >-
*Conditional*. Only relevant for `progress_source` of type
`external`. This boolean indicates whether the requester has the
ability to update the current value of this metric. This returns
`true` if the external metric was created by the requester,
`false` otherwise.
type: boolean
readOnly: true
example: true
owner:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
current_status_update:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
title:
description: The title of the status update.
type: string
example: Status Update - Jun 15
resource_subtype:
type: string
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
The `resource_subtype`s for `status` objects represent the type of
their parent.
enum:
- project_status_update
- portfolio_status_update
- goal_status_update
example: project_status_update
readOnly: true