Create new KPIs, Quarter Priorities, Annual Priorities, or Winning Moves in Rhythm with this API
Method Details
HTTP Method: POST
URL: https://api.rhythm.cloud/api/public/goal
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):
name: Name or title of the KPI, Quarter Priority, Annual Priority or Winning Move. *This is required.
goalType: quarter_priority | qp | annual_priority | ap | winning_move | wm | kpi *This is required.
teamGoal: true | false (default: false - goal will be created as an individual goal)
teamName: Team name in Rhythm for team goals
Note: If you do not specify for goals you create as Team Goals, the new goal will be assigned to the default team for the owner of the goal. If the owner has no default team and you do not specify a team, there will be an error.
ownerUsername: Rhythm Username (usually work email address) for the owner of the new goal (If you do not specify an owner, new goals will have the API Admin setting up the integration assigned as owner)
rank: number
startDate: yyyy-MM-dd
endDate: yyyy-MM-dd
Note: If no start and end dates are provided, start and end dates will be set according to the criteria type - quarter or annual. Quarter Priorities will default to Start and End Dates for the current quarter. KPIs will default to the start date for the current quarter and no end date. If you specify Annual criteria as is the default for Annual Priorities and Winning Moves, then new goals will default to the start and end date for the current year.
description: Additional description or information about the goal
criteria: JSON Object with the following fields: (optional)
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, or 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 Array of JSON Objects, each with the following fields (optional)
name: name or title of the new task related to the new goal *required
Note: you can use the Create Task documentation [LINK] for details other fields that can be added 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
{
"name" : "New Goal created with API",
"goalType" : "KPI",
"rank" : 1,
"teamGoal" : true,
"teamName" : "Product",
"ownerUsername" : "jessica@rhythmsystems.com",
"description" : "some additional info",
"startDate": "2022-10-04",
"criteria" : {
"criteriaType" : "quarter",
"year" : "2022",
"quarter" : 4,
"supergreen" : "20",
"green" : "10",
"red" : "0"},
"tasks" : [
{"name" : " KPI Task 1",
"dueDate" : "2022-08-01"},
{"name" : " KPI Task 2",
"ownerUsername" : "ryan@rhythmsystems.com",
"context" : "Milestone"} ]
}