Returns a single performance review cycle by id. 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 same visibility rules as GET /review-cycles apply: archived, deleted, or otherwise non-visible cycles return 404.
Results
{
"id": "4d3",
"name": "Annual Review 2024",
"description": "Company-wide annual performance review",
"state": "active",
"start_date": "2024-11-01T00:00:00.000Z",
"end_date": "2024-11-30T00:00:00.000Z",
"review_period_start": "2024-01-01T00:00:00.000Z",
"review_period_end": "2024-11-01T00:00:00.000Z",
"timezone": null,
"employee_count": 4,
"draft_count": 2,
"completed_count": 1,
"not_started_count": 1,
"share_start_date": null,
"share_deadline": null,
"sign_deadline": null,
"employee_meeting_deadline": null,
"customization_start_date": "2024-10-01T00:00:00.000Z",
"customization_end_date": "2024-10-15T00:00:00.000Z",
"has_manager_review": true,
"has_self_review": true,
"has_peer_reviews": false,
"has_upwards_reviews": false
}| key | type | description |
|---|---|---|
| id | string | Review cycle SPI key |
| name | string | Name of the review cycle |
| description | string | null | Description of the review cycle |
| state | string | One of: draft, scheduled, in_preparation, active, ended |
| start_date | string | ISO 8601 date the cycle starts |
| end_date | string | ISO 8601 date the cycle ends |
| review_period_start | string | ISO 8601 start of the period under review |
| review_period_end | string | ISO 8601 end of the period under review |
| timezone | string | null | Timezone of the cycle |
| employee_count | integer | Number of employees in the cycle |
| draft_count | integer | Number of reviews in draft |
| completed_count | integer | Number of completed reviews |
| not_started_count | integer | Number of reviews not yet started |
| share_start_date | string | null | ISO 8601 date from which reviews can be shared |
| share_deadline | string | null | ISO 8601 deadline for sharing reviews |
| sign_deadline | string | null | ISO 8601 deadline for signing reviews |
| employee_meeting_deadline | string | null | ISO 8601 deadline for the review meeting |
| customization_start_date | string | null | ISO 8601 start of the form preparation (customization) window |
| customization_end_date | string | null | ISO 8601 end of the form preparation (customization) window |
| has_manager_review | boolean | Whether the cycle includes manager reviews |
| has_self_review | boolean | Whether the cycle includes self reviews |
| has_peer_reviews | boolean | Whether the cycle includes peer reviews |
| has_upwards_reviews | boolean | Whether the cycle includes upward reviews |
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 | 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 cannot view review cycles |
| 404 | No visible review cycle exists with the supplied id |