Returns an employee's review task in a cycle with the reviews, questionnaires and answers the caller may see. 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 be able to view review cycles: either through the View review cycles permission (global or scoped role), or through View employee directory in an account with performance reviews enabled.
The member must participate in the employee's review: as the reviewee, the reviewing manager, a manager higher in the reporting line, a peer or upward reviewer, or as a global or scoped review admin. Otherwise the endpoint returns 404.
Within the task, reviews only contains the reviews the member is allowed to see. Members who are only peer or upward reviewers of the employee see just the review(s) they wrote. Each review is returned in the same shape as GET /review-cycles/:reviewCycleId/tasks/:id/forms/:reviewType.
The view action URL of an active task in GET /review-cycles/:reviewCycleId/tasks points to this endpoint.
Results
{
"id": "4d3",
"status": "ready",
"state": "in_progress",
"review_cycle": {
"id": "4d3",
"name": "Annual Review 2024",
"state": "active",
"customization_start_date": "2024-10-01T00:00:00.000Z",
"customization_end_date": "2024-10-15T00:00:00.000Z"
},
"reviewee": {
"id": "4d4",
"name": "Doe, Jane"
},
"manager": {
"id": "4d3",
"name": "Smith, John"
},
"reviews": [
{
"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": null
},
"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"
]
}
]
}
]
}
},
{
"review": {
"id": "4d4",
"type": "manager",
"status": "ready",
"master_template_id": "1001",
"follower_template_id": null,
"update_form_url": "/spi/v3/review-cycles/4d3/tasks/4d3/forms/manager",
"state": "not_started",
"submit_deadline": "2024-11-20T00:00:00.000Z",
"share_deadline": "2024-11-25T00:00:00.000Z",
"write_url": "/spi/v3/review-cycles/4d3/reviews/4d4"
},
"questionnaire": {
"template_id": "3",
"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 |
|---|---|---|
| id | string | Review task (aggregate) SPI key |
| status | string | Form preparation status. One of: ready, draft, not_ready |
| state | string | Overall state of the task. One of: not_started, in_progress, shared, signed |
| review_cycle | object | id, name, state, customization_start_date, customization_end_date of the cycle |
| reviewee | object | The employee being reviewed: id (SPI key) and name (Lastname, Firstname) |
| manager | object | null | The reviewing manager: id and name |
| reviews | array | Visible reviews, each an object with review and questionnaire (see GET /review-cycles/:reviewCycleId/tasks/:id/forms/:reviewType for the full field list) |
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 employeeId is not a valid SPI key |
| 401 | Missing or invalid token |
| 403 | Missing r_reviews scope, account token without member_id, or the member cannot view review cycles |
| 404 | The employee has no review task in the cycle, the member does not participate in it, or the cycle is archived or deleted |