Employment HeroRetrieves a paginated list of the organisation's performance review periods. Use page_index and item_per_page (default 20, maximum 100) to page through results.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviewsPath Parameters
The ID of the organisation.
Query Parameters
Filter by archived status. Omit to return both archived and active review periods.
Current page index
11Number of items per page
20100Response Body
Returns a paginated list of review periods, ordered by end date (newest first). The response includes page_index, item_per_page, total_pages and total_items.
The unique identifier of the review period.
The title of the review period.
true for a fixed date review, false for a continuous review.
Whether the review period is archived.
The employee review start date (ISO 8601).
The employee review end date (ISO 8601).
The employee lock out date (ISO 8601).
The reviewer (manager) review start date (ISO 8601).
The reviewer (manager) review end date (ISO 8601).
The reviewer (manager) lock out date (ISO 8601).
Continuous reviews: months in the employee review period.
Continuous reviews: days in the employee review period.
Continuous reviews: months in the reviewer review period.
Continuous reviews: days in the reviewer review period.
The review templates used by the review period.
The overall completion status of employee (self) reviews.
The overall completion status of reviewer reviews.
Completed over total employee reviews, e.g. 3/10.
Completed over total reviewer reviews, e.g. 2/10.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "7d1c3a52-9b0e-4f6a-8a43-2e5f1c9d0b11", "title": "Annual Review 2026", "fixed_date": true, "archived": false, "start_date": "2026-07-01", "end_date": "2026-07-31", "lock_out_date": "2026-08-15", "reviewer_start_date": "2026-08-01", "manager_end_date": "2026-08-10", "manager_lock_out_date": "2026-08-20", "employee_period_months": null, "employee_period_days": null, "manager_period_months": null, "manager_period_days": null, "templates": [ { "id": "c4a9e1b7-3f52-4d68-9a10-5b7e2d8f6a01", "name": "Annual Performance Template" } ], "employee_completion": "in_progress", "manager_completion": "not_started", "employee_completion_ratio": "3/10", "manager_completion_ratio": "0/10" }, { "id": "2b8e4f10-6c3d-4a97-b5e2-0d9a7c1f3e22", "title": "Continuous Check-in", "fixed_date": false, "archived": false, "start_date": null, "end_date": null, "lock_out_date": null, "reviewer_start_date": null, "manager_end_date": null, "manager_lock_out_date": null, "employee_period_months": 3, "employee_period_days": 0, "manager_period_months": 3, "manager_period_days": 0, "templates": [ { "id": "e8d2b6f4-1a73-4c95-8b30-9f4c7a1d2e02", "name": "Quarterly Check-in" } ], "employee_completion": "completed", "manager_completion": "in_progress", "employee_completion_ratio": "10/10", "manager_completion_ratio": "4/10" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}Retrieves the full details of a single performance review period.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_idPath Parameters
The ID of the organisation.
The ID of the review period.
Response Body
Returns the full review period, including description, visibility settings, allowed manager roles and attached files. Returns 404 "Could not find the record" if the review period does not exist in the organisation.
The unique identifier of the review period.
The title of the review period.
true for a fixed date review, false for a continuous review.
Whether the review period is archived.
The employee review start date (ISO 8601).
The employee review end date (ISO 8601).
The employee lock out date (ISO 8601).
The reviewer (manager) review start date (ISO 8601).
The reviewer (manager) review end date (ISO 8601).
The reviewer (manager) lock out date (ISO 8601).
Continuous reviews: months in the employee review period.
Continuous reviews: days in the employee review period.
Continuous reviews: months in the reviewer review period.
Continuous reviews: days in the reviewer review period.
The review templates used by the review period.
The overall completion status of employee (self) reviews.
The overall completion status of reviewer reviews.
Completed over total employee reviews, e.g. 3/10.
Completed over total reviewer reviews, e.g. 2/10.
The review description (HTML).
Controls what employees can see of review responses.
The date responses are released to employees (ISO 8601). Used with visibility_all_responses_on_specific_date.
Whether draft responses are published when the review locks out.
Whether primary managers review.
Whether secondary managers review.
Whether an overall score is used.
Whether weighted questions are used.
Manager roles allowed to view the review.
IDs of additional members who can view the review.
Files attached to the review.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "7d1c3a52-9b0e-4f6a-8a43-2e5f1c9d0b11", "title": "Annual Review 2026", "fixed_date": true, "archived": false, "start_date": "2026-07-01", "end_date": "2026-07-31", "lock_out_date": "2026-08-15", "reviewer_start_date": "2026-08-01", "manager_end_date": "2026-08-10", "manager_lock_out_date": "2026-08-20", "employee_period_months": null, "employee_period_days": null, "manager_period_months": null, "manager_period_days": null, "templates": [ { "id": "c4a9e1b7-3f52-4d68-9a10-5b7e2d8f6a01", "name": "Annual Performance Template" } ], "employee_completion": "in_progress", "manager_completion": "not_started", "employee_completion_ratio": "3/10", "manager_completion_ratio": "0/10", "description": "<p>Annual performance review for all employees.</p>", "employee_response_visibility": "visibility_own_responses_only", "employee_responses_release_date": null, "publish_responses": false, "primary_manager_enabled": true, "secondary_manager_enabled": false, "use_overall_score": true, "use_weighted_questions": false, "allowed_manager_roles": [ "primary_manager" ], "additional_viewer_member_ids": [], "files": [ { "file_id": "fil_abc123def456ghi789", "filename": "review-guidelines.pdf", "url": "https://cdn.employmenthero.com/files/review-guidelines.pdf" } ] }}Creates a fixed date performance review period with explicit employee and reviewer dates. Participants are selected with member_ids, group_ids, location_ids and organisation_division_ids.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviewsPath Parameters
The ID of the organisation.
Request Body
The review title.
IDs of the review templates to use.
The review description.
File handles returned by the file upload endpoint to attach to the review.
Publish draft responses when the review locks out.
Use an overall score.
Use weighted questions. Requires use_overall_score to be true.
What employees can see of review responses. visibility_all_responses_on_specific_date is only available for fixed date reviews and requires employee_responses_release_date.
Required when employee_response_visibility is visibility_all_responses_on_specific_date.
Manager roles allowed to view the review.
The employee review start date.
The employee review end date.
The employee lock out date. Must be after the end date.
The reviewer review start date.
The reviewer review end date.
The reviewer lock out date. Must be after the end date.
Days before launch to send a reminder. Minimum 1.
The date reminders are sent.
Reviewer types. Defaults to primary_manager when omitted.
IDs of the employees to include.
IDs of the teams whose members are included.
IDs of the locations whose members are included.
IDs of the divisions whose members are included.
Exclude pending employees. Defaults to false.
Set to true (default) to create a fixed date review.
Response Body
Returns HTTP 201 with the created review period. Validation failures return 422, for example "Lock out date should be after end date", "Reviewer lock out date should be after end date", "Use weighted questions Use overall score must be true" or "Employee responses release date can't be blank".
The unique identifier of the review period.
The title of the review period.
true for a fixed date review, false for a continuous review.
Whether the review period is archived.
The employee review start date (ISO 8601).
The employee review end date (ISO 8601).
The employee lock out date (ISO 8601).
The reviewer (manager) review start date (ISO 8601).
The reviewer (manager) review end date (ISO 8601).
The reviewer (manager) lock out date (ISO 8601).
Continuous reviews: months in the employee review period.
Continuous reviews: days in the employee review period.
Continuous reviews: months in the reviewer review period.
Continuous reviews: days in the reviewer review period.
The review templates used by the review period.
The overall completion status of employee (self) reviews.
The overall completion status of reviewer reviews.
Completed over total employee reviews, e.g. 3/10.
Completed over total reviewer reviews, e.g. 2/10.
The review description (HTML).
Controls what employees can see of review responses.
The date responses are released to employees (ISO 8601). Used with visibility_all_responses_on_specific_date.
Whether draft responses are published when the review locks out.
Whether primary managers review.
Whether secondary managers review.
Whether an overall score is used.
Whether weighted questions are used.
Manager roles allowed to view the review.
IDs of additional members who can view the review.
Files attached to the review.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Annual Review 2026", "review_template_ids": [ "c4a9e1b7-3f52-4d68-9a10-5b7e2d8f6a01" ], "fixed_date": true, "employee_start_date": "2026-07-01", "employee_end_date": "2026-07-31", "employee_lock_out_date": "2026-08-15", "reviewer_start_date": "2026-08-01", "reviewer_end_date": "2026-08-10", "reviewer_lock_out_date": "2026-08-20", "reviewer_types": [ "primary_manager" ], "employee_response_visibility": "visibility_own_responses_only", "member_ids": [ "a1f3c7d9-5e28-4b60-93d4-7c2e8f0b1a03" ] }'Response
{ "data": { "id": "7d1c3a52-9b0e-4f6a-8a43-2e5f1c9d0b11", "title": "Annual Review 2026", "fixed_date": true, "archived": false, "start_date": "2026-07-01", "end_date": "2026-07-31", "lock_out_date": "2026-08-15", "reviewer_start_date": "2026-08-01", "manager_end_date": "2026-08-10", "manager_lock_out_date": "2026-08-20", "employee_period_months": null, "employee_period_days": null, "manager_period_months": null, "manager_period_days": null, "templates": [ { "id": "c4a9e1b7-3f52-4d68-9a10-5b7e2d8f6a01", "name": "Annual Performance Template" } ], "employee_completion": "in_progress", "manager_completion": "not_started", "employee_completion_ratio": "3/10", "manager_completion_ratio": "0/10", "description": "<p>Annual performance review for all employees.</p>", "employee_response_visibility": "visibility_own_responses_only", "employee_responses_release_date": null, "publish_responses": false, "primary_manager_enabled": true, "secondary_manager_enabled": false, "use_overall_score": true, "use_weighted_questions": false, "allowed_manager_roles": [ "primary_manager" ], "additional_viewer_member_ids": [], "files": [ { "file_id": "fil_abc123def456ghi789", "filename": "review-guidelines.pdf", "url": "https://cdn.employmenthero.com/files/review-guidelines.pdf" } ] }}Creates a continuous performance review period by sending fixed_date: false with period lengths in months and days. The visibility_all_responses_on_specific_date visibility option is not available for continuous reviews.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviewsPath Parameters
The ID of the organisation.
Request Body
The review title.
IDs of the review templates to use.
The review description.
File handles returned by the file upload endpoint to attach to the review.
Publish draft responses when the review locks out.
Use an overall score.
Use weighted questions. Requires use_overall_score to be true.
What employees can see of review responses. visibility_all_responses_on_specific_date is only available for fixed date reviews and requires employee_responses_release_date.
Required when employee_response_visibility is visibility_all_responses_on_specific_date.
Manager roles allowed to view the review.
Months in the employee review period.
Days in the employee review period.
Months in the reviewer review period.
Days in the reviewer review period.
Days after the period ends before employees are locked out.
Days after the period ends before managers are locked out.
Days before the period ends to send reminders.
IDs of the employees to include.
IDs of the teams whose members are included.
IDs of the locations whose members are included.
IDs of the divisions whose members are included.
Exclude pending employees. Defaults to false.
Must be false to create a continuous review.
Response Body
Returns HTTP 201 with the created review period. Validation failures return 422, for example "Employee period days Period length must be non-zero" or "Employee response visibility is only available for fixed date reviews".
The unique identifier of the review period.
The title of the review period.
true for a fixed date review, false for a continuous review.
Whether the review period is archived.
The employee review start date (ISO 8601).
The employee review end date (ISO 8601).
The employee lock out date (ISO 8601).
The reviewer (manager) review start date (ISO 8601).
The reviewer (manager) review end date (ISO 8601).
The reviewer (manager) lock out date (ISO 8601).
Continuous reviews: months in the employee review period.
Continuous reviews: days in the employee review period.
Continuous reviews: months in the reviewer review period.
Continuous reviews: days in the reviewer review period.
The review templates used by the review period.
The overall completion status of employee (self) reviews.
The overall completion status of reviewer reviews.
Completed over total employee reviews, e.g. 3/10.
Completed over total reviewer reviews, e.g. 2/10.
The review description (HTML).
Controls what employees can see of review responses.
The date responses are released to employees (ISO 8601). Used with visibility_all_responses_on_specific_date.
Whether draft responses are published when the review locks out.
Whether primary managers review.
Whether secondary managers review.
Whether an overall score is used.
Whether weighted questions are used.
Manager roles allowed to view the review.
IDs of additional members who can view the review.
Files attached to the review.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Continuous Check-in", "review_template_ids": [ "e8d2b6f4-1a73-4c95-8b30-9f4c7a1d2e02" ], "fixed_date": false, "employee_period_months": 3, "employee_period_days": 0, "reviewer_period_months": 3, "reviewer_period_days": 0, "employee_lock_out_days": 7, "manager_lock_out_days": 7, "send_reminder_days": 3, "employee_response_visibility": "visibility_own_responses_only" }'Response
{ "data": { "id": "7d1c3a52-9b0e-4f6a-8a43-2e5f1c9d0b11", "title": "Continuous Check-in", "fixed_date": false, "archived": false, "start_date": null, "end_date": null, "lock_out_date": null, "reviewer_start_date": null, "manager_end_date": null, "manager_lock_out_date": null, "employee_period_months": 3, "employee_period_days": 0, "manager_period_months": 3, "manager_period_days": 0, "templates": [ { "id": "c4a9e1b7-3f52-4d68-9a10-5b7e2d8f6a01", "name": "Annual Performance Template" } ], "employee_completion": "in_progress", "manager_completion": "not_started", "employee_completion_ratio": "3/10", "manager_completion_ratio": "0/10", "description": "<p>Annual performance review for all employees.</p>", "employee_response_visibility": "visibility_own_responses_only", "employee_responses_release_date": null, "publish_responses": false, "primary_manager_enabled": true, "secondary_manager_enabled": false, "use_overall_score": true, "use_weighted_questions": false, "allowed_manager_roles": [ "primary_manager" ], "additional_viewer_member_ids": [], "files": [ { "file_id": "fil_abc123def456ghi789", "filename": "review-guidelines.pdf", "url": "https://cdn.employmenthero.com/files/review-guidelines.pdf" } ] }}Partially updates a performance review period. Only the fields provided are changed. Send archived: true to archive a review period or archived: false to unarchive it.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_idPath Parameters
The ID of the organisation.
The ID of the review period.
Request Body
The review title.
IDs of the review templates to use.
The review description.
File handles returned by the file upload endpoint to attach to the review.
Publish draft responses when the review locks out.
Use an overall score.
Use weighted questions. Requires use_overall_score to be true.
What employees can see of review responses. visibility_all_responses_on_specific_date is only available for fixed date reviews and requires employee_responses_release_date.
Required when employee_response_visibility is visibility_all_responses_on_specific_date.
Manager roles allowed to view the review.
The employee review start date.
The employee review end date.
The employee lock out date. Must be after the end date.
The reviewer review start date.
The reviewer review end date.
The reviewer lock out date. Must be after the end date.
Days before launch to send a reminder. Minimum 1.
The date reminders are sent.
Reviewer types. Defaults to primary_manager when omitted.
Months in the employee review period.
Days in the employee review period.
Months in the reviewer review period.
Days in the reviewer review period.
Days after the period ends before employees are locked out.
Days after the period ends before managers are locked out.
Days before the period ends to send reminders.
true archives the review period, false unarchives it.
Response Body
Returns the updated review period. Only supplied fields change. Fixed date fields apply to fixed date reviews and period fields apply to continuous reviews. Validation failures return 422.
The unique identifier of the review period.
The title of the review period.
true for a fixed date review, false for a continuous review.
Whether the review period is archived.
The employee review start date (ISO 8601).
The employee review end date (ISO 8601).
The employee lock out date (ISO 8601).
The reviewer (manager) review start date (ISO 8601).
The reviewer (manager) review end date (ISO 8601).
The reviewer (manager) lock out date (ISO 8601).
Continuous reviews: months in the employee review period.
Continuous reviews: days in the employee review period.
Continuous reviews: months in the reviewer review period.
Continuous reviews: days in the reviewer review period.
The review templates used by the review period.
The overall completion status of employee (self) reviews.
The overall completion status of reviewer reviews.
Completed over total employee reviews, e.g. 3/10.
Completed over total reviewer reviews, e.g. 2/10.
The review description (HTML).
Controls what employees can see of review responses.
The date responses are released to employees (ISO 8601). Used with visibility_all_responses_on_specific_date.
Whether draft responses are published when the review locks out.
Whether primary managers review.
Whether secondary managers review.
Whether an overall score is used.
Whether weighted questions are used.
Manager roles allowed to view the review.
IDs of additional members who can view the review.
Files attached to the review.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Annual Review 2026 (updated)", "employee_lock_out_date": "2026-08-20" }'Response
{ "data": { "id": "7d1c3a52-9b0e-4f6a-8a43-2e5f1c9d0b11", "title": "Annual Review 2026 (updated)", "fixed_date": true, "archived": false, "start_date": "2026-07-01", "end_date": "2026-07-31", "lock_out_date": "2026-08-15", "reviewer_start_date": "2026-08-01", "manager_end_date": "2026-08-10", "manager_lock_out_date": "2026-08-20", "employee_period_months": null, "employee_period_days": null, "manager_period_months": null, "manager_period_days": null, "templates": [ { "id": "c4a9e1b7-3f52-4d68-9a10-5b7e2d8f6a01", "name": "Annual Performance Template" } ], "employee_completion": "in_progress", "manager_completion": "not_started", "employee_completion_ratio": "3/10", "manager_completion_ratio": "0/10", "description": "<p>Annual performance review for all employees.</p>", "employee_response_visibility": "visibility_own_responses_only", "employee_responses_release_date": null, "publish_responses": false, "primary_manager_enabled": true, "secondary_manager_enabled": false, "use_overall_score": true, "use_weighted_questions": false, "allowed_manager_roles": [ "primary_manager" ], "additional_viewer_member_ids": [], "files": [ { "file_id": "fil_abc123def456ghi789", "filename": "review-guidelines.pdf", "url": "https://cdn.employmenthero.com/files/review-guidelines.pdf" } ] }}Deletes a performance review period. The deletion is processed asynchronously and the endpoint responds with HTTP 202.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_idPath Parameters
The ID of the organisation.
The ID of the review period.
Response Body
Returns HTTP 202 Accepted. The review period is deleted asynchronously.
Whether the deletion was accepted.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "success": true }}Retrieves a paginated list of the employees participating in a review period, with the status of their self review and of each assigned reviewer. Use page_index and item_per_page (default 20, maximum 100) to page through results.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_id/participantsPath Parameters
The ID of the organisation.
The ID of the review period.
Query Parameters
Current page index
11Number of items per page
20100Response Body
Returns a paginated list of participants with their reviewers. The response includes page_index, item_per_page, total_pages and total_items.
The name of the employee being reviewed.
The status of the employee self review.
The reviewers assigned to the employee.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/:performance_review_id/participants" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "employee_name": "Jane Citizen", "self_review_status": "completed", "reviewers": [ { "name": "John Smith", "type": "primary_manager", "status": "in_progress" } ] }, { "employee_name": "Sam Lee", "self_review_status": "not_started", "reviewers": [ { "name": "John Smith", "type": "primary_manager", "status": "not_started" }, { "name": "Priya Nair", "type": "secondary_manager", "status": "not_started" } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}Uploads an attachment for a performance review. Pass the returned file_id in file_ids when creating or updating a review period.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/file_uploadsPath Parameters
The ID of the organisation.
Request Body
The file to upload via multipart/form-data. Maximum 10 MB. Accepted formats: JPG, JPEG, PNG, PDF, DOC, DOCX.
Response Body
Returns an opaque file_id and the uploaded file URL on HTTP 200. Unsupported types return 422 "File type is not supported. Accepted formats: JPG, JPEG, PNG, PDF, DOC, DOCX" and oversized files return 422 "File size exceeds the 10 MB limit".
An opaque file handle to pass in file_ids when creating or updating a review period.
The URL of the uploaded file.
The sanitized filename of the uploaded file.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/performance_reviews/file_uploads" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "file=@/path/to/review-guidelines.pdf"Response
{ "data": { "file_id": "fil_abc123def456ghi789", "url": "https://cdn.employmenthero.com/files/review-guidelines.pdf", "filename": "review-guidelines.pdf" }}