get
https://{subdomain}.workable.com/spi/v3/review-cycles//reviews/
Returns a review with its questionnaire and saved answers, for the review's reviewer. Required scope: r_reviews.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
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 of the reviewer (the request is then evaluated as that member). An account token without member_id gets 403 Account tokens need a member_id for this operation.
Only the reviewer of the review (the member's employee record must be the assigned reviewer) can call this endpoint; anyone else receives 403, regardless of admin permissions. Review ids are discovered via the actions.view.url of the reviews in GET /review-cycles/:reviewCycleId/tasks.
The response has the same shape as GET /review-cycles/:reviewCycleId/tasks/:id/forms/:reviewType. While the review is not yet submitted, review.write_url points to PUT /review-cycles/:reviewCycleId/reviews/:id, which saves or submits the answers.
Results
{
"review": {
"id": "4d3",
"type": "self",
"status": "ready",
"master_template_id": "1000",
"follower_template_id": null,
"update_form_url": "/spi/v3/review-cycles/4d3/tasks/4d3/forms/self",
"state": "draft",
"submit_deadline": "2024-11-30T00:00:00.000Z",
"share_deadline": "2024-11-15T00:00:00.000Z",
"write_url": "/spi/v3/review-cycles/4d3/reviews/4d3"
},
"questionnaire": {
"template_id": "1",
"overall_rating": 4,
"sections": [
{
"id": "25012984-7b5b-57df-86ce-43d640f23648",
"name": "<p>Job Performance</p>",
"rating": 4,
"questions": [
{
"id": "25012946-72fb-5069-8797-6b5ccc2912dd",
"body": "<p>How do you feel you have performed in fulfilling the core responsibilities of your role?</p>",
"position": 0,
"section_id": "25012984-7b5b-57df-86ce-43d640f23648",
"answer": "I delivered three major projects on time and improved our release process.",
"type": "paragraph"
},
{
"id": "2501297b-1920-5e4c-b21b-fc3caf56a162",
"body": "<p>What are your main pillars of improvement?</p>",
"position": 1,
"section_id": "25012984-7b5b-57df-86ce-43d640f23648",
"answer": null,
"type": "multiple_choice",
"metadata": {
"mandatory": true,
"answer_options": {
"choices": {
"1": "Team building",
"2": "Technical skills",
"3": "Interpersonal skills"
}
}
},
"choices": [
"Technical skills",
"Interpersonal skills"
]
},
{
"id": "2501297b-1920-5e4c-b21b-fc3caf56b295",
"body": "<p>Section Rating</p>",
"position": 2,
"section_id": "25012984-7b5b-57df-86ce-43d640f23648",
"answer": null,
"type": "numeric_rated",
"metadata": {
"mandatory": true,
"semantic_type": "section_rating",
"rating_options": {}
},
"choices": [
"4"
]
}
]
},
{
"id": "25012984-7b5b-57df-86ce-43d640f23610",
"name": "<p>Overall rating</p>",
"rating": null,
"questions": [
{
"id": "2501297b-1920-5e4c-b21b-fc3caf56b335",
"body": "<p>Overall rating</p>",
"position": 0,
"section_id": "25012984-7b5b-57df-86ce-43d640f23610",
"answer": null,
"type": "numeric_rated",
"metadata": {
"mandatory": true,
"semantic_type": "overall_rating",
"rating_options": {}
},
"choices": [
"4"
]
}
]
}
]
}
}| 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 |
| 401 | Missing or invalid token |
| 403 | Missing r_reviews scope, account token without member_id, or the member is not the reviewer of this review |
| 404 | The review does not exist in the cycle, or the cycle is archived or deleted |