Returns a review of a review task together with its questionnaire. Required scope: r_reviews.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
This endpoint uses ther_reviewsscope, which must be enabled through the Integrations section found within the Settings menu.
Requires a user token, or an account token together with the member_id query parameter (the request is then evaluated with that member's permissions). An account token without member_id gets 403 Account tokens need a member_id for this operation. member_id is ignored for user tokens.
The member must have the View review cycles permission, be the reviewee, be the task's reviewing manager, or be a manager higher in the reviewee's reporting line.
Returns the review of the given type within the task (with its status and template ids) together with its questionnaire (sections and questions). Any answers saved so far are merged into the questions. Task ids (:id) and the available review types are discovered via GET /review-cycles/:reviewCycleId/tasks; each review there carries this endpoint as its update_form_url. Use PUT on the same URL to customize the form.
When a task has several reviews of the same type (for example multiple peer reviews), the first one is returned.
Path parameters
| Parameter | Type | Description |
|---|---|---|
| reviewCycleId | string | Review cycle SPI key |
| id | string | Review task (aggregate) SPI key |
| reviewType | string | One of: self, manager, peer, upwards |
Results
{
"review": {
"id": "4d6",
"type": "manager",
"status": "draft",
"master_template_id": "3001",
"follower_template_id": null,
"update_form_url": "/spi/v3/review-cycles/4d6/tasks/4d4/forms/manager",
"state": "not_started",
"submit_deadline": "2024-11-25T00:00:00.000Z",
"share_deadline": "2024-11-27T00:00:00.000Z",
"write_url": "/spi/v3/review-cycles/4d6/reviews/4d6"
},
"questionnaire": {
"template_id": "7",
"overall_rating": null,
"sections": [
{
"id": "25012962-fd35-5082-aaed-dafc65bb3c29",
"name": "<p>Job Performance</p>",
"rating": null,
"questions": [
{
"id": "25012920-c56d-5b70-b968-834e49ed95d4",
"body": "<p>Are there any areas where the employee's performance could improve?</p>",
"position": 0,
"section_id": "25012962-fd35-5082-aaed-dafc65bb3c29",
"type": "paragraph"
},
{
"id": "2501297b-1920-5e4c-b21b-fc3caf56b265",
"body": "<p>Section Rating</p>",
"position": 1,
"section_id": "25012962-fd35-5082-aaed-dafc65bb3c29",
"type": "numeric_rated",
"metadata": {
"mandatory": true,
"semantic_type": "section_rating",
"rating_options": {}
}
}
]
},
{
"id": "25012902-3adc-4a89-88a0-62a105b06fdd",
"name": "<p>Overall Rating</p>",
"rating": null,
"questions": [
{
"id": "2501297b-1920-5e4c-b21b-fc3caf56b335",
"body": "<p>Overall Rating</p>",
"position": 0,
"section_id": "25012902-3adc-4a89-88a0-62a105b06fdd",
"type": "custom_rated",
"metadata": {
"mandatory": true,
"semantic_type": "overall_rating",
"rating_options": {
"1": "Meets expectations",
"2": "Exceeds expectations"
}
}
}
]
}
]
}
}| key | type | description |
|---|---|---|
| review | object | The review |
| review.id | string | Review SPI key |
| review.type | string | One of: self, manager, peer, upwards |
| review.status | string | Form status: ready once the review's form has been finalized, otherwise draft |
| review.master_template_id | string | null | Id of the master template configured for this review type in the cycle |
| review.follower_template_id | string | null | Id of the customized (follower) template for this review; null if the form has not been customized |
| review.update_form_url | string | Relative URL of this review's form endpoint (GET to read, PUT to customize) |
| review.state | string | Answering state. One of: not_started, draft, submitted |
| review.submit_deadline | string | null | ISO 8601 deadline for submitting the review |
| review.share_deadline | string | null | ISO 8601 deadline for sharing the review |
| review.write_url | string | null | Relative URL to submit answers. Set only when the caller is the reviewer and the review is not yet submitted |
| questionnaire | object | The review's questionnaire, merged with any answers saved so far |
| questionnaire.template_id | string | null | Id of the template the questionnaire was built from |
| questionnaire.overall_rating | number | null | Overall rating, when saved |
| questionnaire.sections | array | Ordered list of sections |
| questionnaire.sections[].id | string | Section id |
| questionnaire.sections[].name | string | Section title (may contain HTML) |
| questionnaire.sections[].rating | number | null | Section rating, when saved |
| questionnaire.sections[].questions | array | Ordered list of questions |
| questionnaire.sections[].questions[].id | string | Question id (UUID) |
| questionnaire.sections[].questions[].body | string | Question text (may contain HTML) |
| questionnaire.sections[].questions[].position | integer | Position within the section |
| questionnaire.sections[].questions[].section_id | string | Id of the parent section |
| questionnaire.sections[].questions[].type | string | Question type in snake_case. One of: paragraph, paragraph_star_rated, paragraph_numeric_rated, paragraph_custom_rated, single_choice, multiple_choice, star_rated, numeric_rated, custom_rated |
| questionnaire.sections[].questions[].answer | string | null | Free-text answer. Omitted when nothing has been saved for the question |
| questionnaire.sections[].questions[].choices | array | Selected choices. Choice keys are replaced by their labels when the question has answer_options; for rating questions this holds the selected rating value. Omitted when empty |
| questionnaire.sections[].questions[].metadata | object | Optional question metadata: mandatory (boolean), semantic_type (section_rating or overall_rating), rating_options (map of rating value to label), answer_options.choices (map of choice key to label) |
Error responses
Error bodies come in three shapes. 400 validation errors are a JSON object keyed by the invalid parameter, e.g. {"limit": {"code": "number.max", "message": "\"limit\" must be less than or equal to 200"}}. 401 and 403 are plain-text bodies, e.g. Required scopes missing: ["r_reviews"], or Forbidden when the member lacks permission. 404 is JSON, e.g. {"message": "Review cycle not found"}.
| Status | Condition |
|---|---|
| 400 | reviewCycleId or id is not a valid SPI key, or reviewType is not one of self, manager, peer, upwards |
| 401 | Missing or invalid token |
| 403 | Missing r_reviews scope, account token without member_id, or the member is not allowed to view the review's form |
| 404 | The task does not exist or does not belong to the cycle, or it has no review of the requested type |