Edit Goal name, dates, tasks and other attributes in Rhythm with this API.
Method Details
HTTP Method: PUT
URL: https://api.rhythm.cloud/api/public/goal/{id}
Content Type: application/json
Response Format: json
Requires Authentication? Yes
HTTP header: Bearer {oauth token}
Request Body
JSON Object, containing the following fields (strings should be double quoted, numbers and boolean not):
Note: if a field is omitted, the existing value in Rhythm will not be updated. If you’d like to update an existing field to null, then a JSON Null value should be explicitly specified
id: ID of the KPI, Quarter Priority, Annual Priority, or Winning Move that the update is for. *This is required. You can find the Goal ID by clicking on the “More Actions” button on the Goal and choosing “Show ID for API” or by downloading the Goal List report.
name: Name or title of the KPI, Quarter Priority, Annual Priority or Winning Move
teamGoal: true | false
teamName: Team name in Rhythm for team goals (Required if changing teamGoal from false to true)
ownerUsername: Rhythm Username (usually work email address) for the owner of the new goal
rank: number
startDate: yyyy-MM-dd
endDate: yyyy-MM-dd
description: Additional description or information about the goal
completed: true | false
Note: You cannot convert to a new Goal type via this API.
criteria: JSON Object
criteriaType: “annual” | “quarter” (If you do not specify, the Goal will be created with the default criteria for the Goal type - Quarter Priorities and KPIs will be quarter criteria, and Annual Priorities and Winning Moves will be annual. If you do specify a type, you must provide the Year for Annual criteria and the Year and Quarter for Quarter criteria)
year: yyyy (number) *required if criteriaType is annual or quarter
quarterNo: 1 | 2 | 3 | 4 (number) *required if criteriaType is quarter
red: the Red Success Criteria for the goal
yellow: the Yellow Success Criteria for the goal
green: the Green Success Criteria for the goal
supergreen: the SuperGreen Success Criteria for the goal
tasks: JSON Object with the following fields
For creating new tasks on the goal:
name: name or title of the new task related to the new goal *This is required
For updating existing tasks on the goal:
id: ID of the Task that the update is for. *This is required. You can find the Task ID by clicking on the “More Actions” button on the Goal and choosing “Show ID for API”
name: name of the Task
Note: You can use the Create Task documentation for details on other fields that can be added or updated via API on a new task.
Response
If all items in the request were processed successfully, you will receive a http code 200 (OK), with a JSON of {"success":true} in the response body.
If the access token has expired, you will receive a http code 401 (unauthorized).
If some items in the request processed successfully, and some failed, you will receive a http code 202 (Accepted). If all items in the request failed, the API call will result in a http code 400 (bad request). In both these instances, the response body will contain a JSON array, where each JSON Object contains additional information about the failed item, the following format:
[{
"error": "error code used by Rhythm Systems for further trouble shooting",
"error_description": "description of the error encountered in the API call",
"data": "{the data received by Rhythm in your API call}"
},
{
"error": "error code used by Rhythm Systems for further trouble shooting",
"error_description": "description of the error encountered in the API call",
"data": "{the data received by Rhythm in your API call}"
}]
Request Body Sample
{
"id" : "21ceb947-0b5b-4822-b8b5-32067c1befbd",
"name" : "Edited name of goal",
"ownerUsername" : "jessica@rhythmsystems.com",
"completed" : true,
"teamGoal" : true,
"teamName" : "Product",
"tasks" : [
{"name" : "new task on this goal"},
{"id" : "bc9e0d1c-2480-4204-837a-cfc45fcba410",
"name" : "EDITED task"}]
}