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