Employment HeroTalent Assessment
Each assessment rates an employee's performance and potential from 1 to 3, where 3 is the highest. The 9-box category is derived from the two ratings.
This endpoint returns the most recent talent assessment for each employee the caller can see on the 9-box talent grid. Results are paginated and ordered by assessment date, newest first.
Use start_date and end_date to limit the assessments considered. When a date range is given, each employee is returned with their latest assessment inside that range, and employees with no assessment in the range are left out.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/talent_assessmentsPath Parameters
The ID of the organisation to retrieve talent assessments for.
Query Parameters
Only consider assessments made on or after this UTC date (YYYY-MM-DD format).
Only consider assessments made on or before this UTC date (YYYY-MM-DD format). The whole day is included.
Current page index
11Number of items per page
20100Response Body
A JSON object with a data property that contains an array of talent assessment objects and pagination information. Each item is the latest assessment for one employee the caller can see on the 9-box talent grid, ordered by assessment date with the newest first. Items do not include an id. Use the employee history endpoint to find the id of a specific assessment.
The UUID of the employee being assessed.
The UUID of the employee who submitted the assessment.
The full name of the reviewer, as recorded when the assessment was submitted.
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
The 9-box talent category for the combination of performance and potential ratings. Null when either rating is 0.
Whether the employee can see the ratings.
Whether the employee can see the manager comment.
The comment from the reviewer. Null when there is no comment.
The date and time the assessment was made in RFC 3339 format.
The date and time the assessment was last updated in RFC 3339 format.
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/employees/talent_assessments" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "employee_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 3, "potential_rating": 2, "category": "high_performer", "scores_visible_to_employee": true, "comment_visible_to_employee": false, "manager_comment": "Strong quarter, consistently delivering results across the team.", "assessed_at": "2026-06-01T14:30:00Z", "updated_at": "2026-06-01T14:30:00Z" }, { "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 2, "potential_rating": 3, "category": "high_potential", "scores_visible_to_employee": false, "comment_visible_to_employee": false, "manager_comment": null, "assessed_at": "2026-05-20T09:00:00Z", "updated_at": "2026-05-20T09:00:00Z" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint returns the most recent talent assessment for an employee. The response does not include the assessment id. Use the employee history endpoint to find it.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessmentPath Parameters
The ID of the organisation the employee belongs to.
The ID of the employee to retrieve the talent assessment for.
Response Body
The UUID of the employee being assessed.
The UUID of the employee who submitted the assessment.
The full name of the reviewer, as recorded when the assessment was submitted.
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
The 9-box talent category for the combination of performance and potential ratings. Null when either rating is 0.
Whether the employee can see the ratings.
Whether the employee can see the manager comment.
The comment from the reviewer. Null when there is no comment.
The date and time the assessment was made in RFC 3339 format.
The date and time the assessment was last updated in RFC 3339 format.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessment" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "employee_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 3, "potential_rating": 2, "category": "high_performer", "scores_visible_to_employee": true, "comment_visible_to_employee": false, "manager_comment": "Strong quarter, consistently delivering results across the team.", "assessed_at": "2026-06-01T14:30:00Z", "updated_at": "2026-06-01T14:30:00Z" }}This endpoint returns every talent assessment for an employee, newest first. Each item includes the assessment id, which you need to update an assessment. Results are paginated.
Use start_date and end_date to limit the assessments returned. The previous ratings are always taken from the full history, so a date range does not change them.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessmentsPath Parameters
The ID of the organisation the employee belongs to.
The ID of the employee to retrieve the talent assessment history for.
Query Parameters
Only return assessments made on or after this UTC date (YYYY-MM-DD format).
Only return assessments made on or before this UTC date (YYYY-MM-DD format). The whole day is included.
Current page index
11Number of items per page
20100Response Body
A JSON object with a data property that contains an array of talent assessment objects and pagination information. Each item is one assessment for the employee, ordered with the newest first. Each item includes the previous performance and potential ratings from the assessment made before it, which are null for the first assessment.
Unique identifier for the talent assessment.
The UUID of the employee being assessed.
The UUID of the employee who submitted the assessment.
The full name of the reviewer, as recorded when the assessment was submitted.
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
The 9-box talent category for the combination of performance and potential ratings. Null when either rating is 0.
Whether the employee can see the ratings.
Whether the employee can see the manager comment.
The comment from the reviewer. Null when there is no comment.
The date and time the assessment was made in RFC 3339 format.
The date and time the assessment was last updated in RFC 3339 format.
The date and time the manager comment was last updated. This value is not tracked yet, so it is always null.
The performance rating from the assessment made immediately before this one. Null for the first assessment.
The potential rating from the assessment made immediately before this one. Null for the first assessment.
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/employees/:employee_id/talent_assessments" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "c3a1d9e4-7b2f-4f6a-9e1d-2a5b8c7d6e4f", "employee_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 3, "potential_rating": 2, "category": "high_performer", "scores_visible_to_employee": true, "comment_visible_to_employee": false, "manager_comment": "Strong quarter, consistently delivering results across the team.", "assessed_at": "2026-06-01T14:30:00Z", "updated_at": "2026-06-01T14:30:00Z", "comment_updated_at": null, "previous_performance_rating": 1, "previous_potential_rating": 1 }, { "id": "d4b2e0f5-8c3a-4a7b-8f2e-3b6c9d8e7f50", "employee_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 1, "potential_rating": 1, "category": "risk", "scores_visible_to_employee": false, "comment_visible_to_employee": false, "manager_comment": null, "assessed_at": "2026-03-15T10:00:00Z", "updated_at": "2026-03-15T10:00:00Z", "comment_updated_at": null, "previous_performance_rating": null, "previous_potential_rating": null } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint creates a talent assessment for an employee. The user who authorises the request is recorded as the reviewer.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessmentsPath Parameters
The ID of the organisation the employee belongs to.
The ID of the employee to create the talent assessment for.
Request Body
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
A comment from the reviewer. Can be up to 1000 characters.
Whether the employee can see the manager comment.
Whether the employee can see the ratings.
Response Body
Returns HTTP 201 Created with the new talent assessment. The reviewer is the user who authorised the request.
Unique identifier for the talent assessment.
The UUID of the employee being assessed.
The UUID of the employee who submitted the assessment.
The full name of the reviewer, as recorded when the assessment was submitted.
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
The 9-box talent category for the combination of performance and potential ratings. Null when either rating is 0.
Whether the employee can see the ratings.
Whether the employee can see the manager comment.
The comment from the reviewer. Null when there is no comment.
The date and time the assessment was made in RFC 3339 format.
The date and time the assessment was last updated in RFC 3339 format.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessments" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "performance_rating": 3, "potential_rating": 2, "manager_comment": "Strong quarter, consistently delivering results across the team.", "comment_visible_to_employee": false, "scores_visible_to_employee": true }'Response
{ "data": { "id": "c3a1d9e4-7b2f-4f6a-9e1d-2a5b8c7d6e4f", "employee_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 3, "potential_rating": 2, "category": "high_performer", "scores_visible_to_employee": true, "comment_visible_to_employee": false, "manager_comment": "Strong quarter, consistently delivering results across the team.", "assessed_at": "2026-06-01T14:30:00Z", "updated_at": "2026-06-01T14:30:00Z" }}This endpoint updates an existing talent assessment for an employee. Only the fields provided in the request are changed; all other fields keep their current values. Get the assessment_id from the create response or from the employee history endpoint.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessments/:assessment_idPath Parameters
The ID of the organisation the employee belongs to.
The ID of the employee the talent assessment belongs to.
The ID of the talent assessment to update.
Request Body
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
A comment from the reviewer. Can be up to 1000 characters. Send null to remove the comment.
Whether the employee can see the manager comment.
Whether the employee can see the ratings.
Response Body
The updated talent assessment. Fields not included in the request keep their current values.
Unique identifier for the talent assessment.
The UUID of the employee being assessed.
The UUID of the employee who submitted the assessment.
The full name of the reviewer, as recorded when the assessment was submitted.
The performance rating, from 1 to 3. A rating of 3 is the highest.
The potential rating, from 1 to 3. A rating of 3 is the highest.
The 9-box talent category for the combination of performance and potential ratings. Null when either rating is 0.
Whether the employee can see the ratings.
Whether the employee can see the manager comment.
The comment from the reviewer. Null when there is no comment.
The date and time the assessment was made in RFC 3339 format.
The date and time the assessment was last updated in RFC 3339 format.
The date and time the manager comment was last updated. This value is not tracked yet, so it is always null.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/talent_assessments/:assessment_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "performance_rating": 2, "manager_comment": "Revised after the calibration session." }'Response
{ "data": { "id": "c3a1d9e4-7b2f-4f6a-9e1d-2a5b8c7d6e4f", "employee_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "reviewer_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "reviewer_name": "Alice Chen", "performance_rating": 2, "potential_rating": 2, "category": "core_player", "scores_visible_to_employee": true, "comment_visible_to_employee": false, "manager_comment": "Revised after the calibration session.", "assessed_at": "2026-06-01T14:30:00Z", "updated_at": "2026-06-05T09:15:00Z", "comment_updated_at": null }}