Employment HeroGoal
Note
Goals (OKRs) are available to organisations with the OKRs entitlement. Access is governed by the same permission model that controls what users see in the Employment Hero platform.
This endpoint retrieves a paginated list of goals for the organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goalsPath Parameters
The UUID of the organisation to retrieve goals for.
Query Parameters
Filter by goal type.
Filter by health status.
Filter goals by status.
Filter by the UUID of the goal owner.
Filter by the UUID of the group (team) associated with the goal. Only relevant for goal_type=group.
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of goals. Each entry in the array is a separate goal object. If there are no more goals belonging to your organisation, the resulting array will be empty.
Note: Goals with visibility_type=participants are only returned to the owner and key result collaborators on that goal. Goals with visibility_type=groups are only returned to members of the associated group.
Unique identifier for the goal.
The name of the goal.
The type of the goal.
The description of the goal.
The UUID of the employee who owns the goal.
The full name of the employee who owns the goal.
The UUID of the employee who created the goal.
The full name of the employee who created the goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD).
The health status of the goal.
Who can see the goal. everyone is visible to all organisation members; participants is visible only to the owner and key result collaborators; groups is visible only to members of the associated group (only valid for goal_type=group).
The UUID of the parent goal this goal is aligned to.
The name of the parent goal this goal is aligned to.
Whether progress on this goal feeds into the parent goal's progress.
The UUID of the group associated with this goal. Only populated for goal_type=group.
The name of the group associated with this goal. Only populated for goal_type=group.
Whether the goal is active or archived.
The percentage completion of the goal (0 to 100), rounded to two decimal places.
The number of active key results on this goal.
The number of active child goals aligned to this goal.
Files attached to the goal.
The date and time the goal was created in RFC 3339 format.
The date and time the goal 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/goals" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Improve customer satisfaction to 90%", "goal_type": "company", "description": "Drive NPS and CSAT scores by improving product quality and support response times.", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "due_date": "2026-12-31", "health_status": "on_track", "visibility_type": "everyone", "parent_id": null, "parent_name": null, "feed_to_parent": false, "group_id": null, "group_name": null, "status": "active", "progress": 62.5, "key_results_count": 3, "children_count": 2, "attachments": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Launch APAC expansion into three new markets", "goal_type": "group", "description": null, "owner_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "owner_name": "Alice Chen", "creator_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "creator_name": "Alice Chen", "due_date": "2026-09-30", "health_status": "making_progress", "visibility_type": "groups", "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "parent_name": "Improve customer satisfaction to 90%", "feed_to_parent": true, "group_id": "143ed07a-e7d1-4c19-ade6-b0ffe9123d19", "group_name": "Business Development", "status": "active", "progress": 40, "key_results_count": 2, "children_count": 0, "attachments": [ { "id": 101, "name": "APAC-expansion-plan.pdf", "url": "https://example.com/attachments/APAC-expansion-plan.pdf" } ], "created_at": "2026-02-01T10:00:00+00:00", "updated_at": "2026-06-01T11:15:00+00:00" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint retrieves a specific goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_idPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to retrieve.
Response Body
Unique identifier for the goal.
The name of the goal.
The type of the goal.
The description of the goal.
The UUID of the employee who owns the goal.
The full name of the employee who owns the goal.
The UUID of the employee who created the goal.
The full name of the employee who created the goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD).
The health status of the goal.
Who can see the goal. everyone is visible to all organisation members; participants is visible only to the owner and key result collaborators; groups is visible only to members of the associated group (only valid for goal_type=group).
The UUID of the parent goal this goal is aligned to.
The name of the parent goal this goal is aligned to.
Whether progress on this goal feeds into the parent goal's progress.
The UUID of the group associated with this goal. Only populated for goal_type=group.
The name of the group associated with this goal. Only populated for goal_type=group.
Whether the goal is active or archived.
The percentage completion of the goal (0 to 100), rounded to two decimal places.
The number of active key results on this goal.
The number of active child goals aligned to this goal.
Files attached to the goal.
The date and time the goal was created in RFC 3339 format.
The date and time the goal was last updated in RFC 3339 format.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Improve customer satisfaction to 90%", "goal_type": "company", "description": "Drive NPS and CSAT scores by improving product quality and support response times.", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "due_date": "2026-12-31", "health_status": "on_track", "visibility_type": "everyone", "parent_id": null, "parent_name": null, "feed_to_parent": false, "group_id": null, "group_name": null, "status": "active", "progress": 62.5, "key_results_count": 3, "children_count": 2, "attachments": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }}This endpoint creates a new goal within an organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goalsPath Parameters
The UUID of the organisation to create the goal in.
Request Body
The title of the goal (max 255 characters).
The type of the goal.
The UUID of the employee who owns this goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD). Must be a future date.
A longer description providing context or explanation for the goal.
The UUID of an existing goal to align this goal to.
The UUID of the group to associate with this goal. Required when goal_type=group.
When true, this goal's progress rolls up into the parent goal's progress calculation. Ignored if parent_id is not set. Default: false.
Who can see the goal.
everyone— visible to all organisation membersparticipants— visible only to the owner and key result collaboratorsgroups— visible only to members of the associated group (only valid whengoal_type=group)
Default: participants
An array of file IDs to attach to this goal. IDs are obtained from the Upload a File endpoint.
Response Body
Returns the newly created goal.
Unique identifier for the goal.
The name of the goal.
The type of the goal.
The description of the goal.
The UUID of the employee who owns the goal.
The full name of the employee who owns the goal.
The UUID of the employee who created the goal.
The full name of the employee who created the goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD).
The health status of the goal.
Who can see the goal. everyone is visible to all organisation members; participants is visible only to the owner and key result collaborators; groups is visible only to members of the associated group (only valid for goal_type=group).
The UUID of the parent goal this goal is aligned to.
The name of the parent goal this goal is aligned to.
Whether progress on this goal feeds into the parent goal's progress.
The UUID of the group associated with this goal. Only populated for goal_type=group.
The name of the group associated with this goal. Only populated for goal_type=group.
Whether the goal is active or archived.
The percentage completion of the goal (0 to 100), rounded to two decimal places.
The number of active key results on this goal.
The number of active child goals aligned to this goal.
Files attached to the goal.
The date and time the goal was created in RFC 3339 format.
The date and time the goal was last updated in RFC 3339 format.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Improve customer satisfaction to 90%", "goal_type": "company", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "due_date": "2026-12-31", "description": "Drive NPS and CSAT scores by improving product quality and support response times.", "visibility_type": "everyone", "feed_to_parent": false, "attachment_ids": [] }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Improve customer satisfaction to 90%", "goal_type": "company", "description": "Drive NPS and CSAT scores by improving product quality and support response times.", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "due_date": "2026-12-31", "health_status": "on_track", "visibility_type": "everyone", "parent_id": null, "parent_name": null, "feed_to_parent": false, "group_id": null, "group_name": null, "status": "active", "progress": 62.5, "key_results_count": 3, "children_count": 2, "attachments": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }}This endpoint updates the details of an existing goal. You can update any combination of the goal's name, description, due date, type, owner, parent alignment, visibility, and attachments.
Attachments are replaced, not merged
When attachment_ids is provided, it replaces the goal's entire
attachment set. Any attachment not listed is removed. To clear all
attachments, pass an empty array ([]). To leave attachments unchanged, omit
attachment_ids entirely.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_idPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to update.
Request Body
The name of the goal. Cannot be blank if provided.
The description of the goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD). Must not be earlier than the due date of any key result on this goal.
The type of the goal.
The UUID of the member to set as the goal owner. Must be a member of the organisation; returns 404 if not found.
The UUID of the goal to align this goal under. Must be a visible goal within the organisation; returns 404 if not found or not accessible.
The UUID of the group to associate with this goal. Only takes effect when goal_type is (or is already) group. Returns 404 if the group is not found in the organisation.
Who can see the goal. everyone is visible to all organisation members; participants is visible only to the owner and key result collaborators; groups is visible only to members of the associated group (only valid for goal_type=group).
Whether progress on this goal feeds into the parent goal's progress.
The complete set of file UUIDs to attach to the goal. Replaces the existing attachment set — any attachment not included is removed. Pass an empty array ([]) to remove all attachments. Omit this field entirely to leave attachments unchanged.
Response Body
Returns HTTP 200 with the full updated goal object on success.
Unique identifier for the goal.
The name of the goal.
The type of the goal.
The description of the goal.
The UUID of the employee who owns the goal.
The full name of the employee who owns the goal.
The UUID of the employee who created the goal.
The full name of the employee who created the goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD).
The health status of the goal.
Who can see the goal. everyone is visible to all organisation members; participants is visible only to the owner and key result collaborators; groups is visible only to members of the associated group (only valid for goal_type=group).
The UUID of the parent goal this goal is aligned to.
The name of the parent goal this goal is aligned to.
Whether progress on this goal feeds into the parent goal's progress.
The UUID of the group associated with this goal. Only populated for goal_type=group.
The name of the group associated with this goal. Only populated for goal_type=group.
Whether the goal is active or archived.
The percentage completion of the goal (0 to 100), rounded to two decimal places.
The number of active key results on this goal.
The number of active child goals aligned to this goal.
Files attached to the goal.
The date and time the goal was created in RFC 3339 format.
The date and time the goal was last updated in RFC 3339 format.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Improve customer satisfaction to 90%", "due_date": "2026-12-31", "goal_type": "company", "visibility_type": "everyone", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a" }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Improve customer satisfaction to 90%", "goal_type": "company", "description": "Drive NPS and CSAT scores by improving product quality and support response times.", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "due_date": "2026-12-31", "health_status": "on_track", "visibility_type": "everyone", "parent_id": null, "parent_name": null, "feed_to_parent": false, "group_id": null, "group_name": null, "status": "active", "progress": 62.5, "key_results_count": 3, "children_count": 2, "attachments": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }}This endpoint retrieves a paginated list of comments for a goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/commentsPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to retrieve comments for.
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of comments, ordered from most recent to oldest. Each entry is a separate comment object. If there are no more comments, the resulting array will be empty.
Each comment is one of two types: a plain text note (has content, checkin_changes is omitted) or a check-in update (has checkin_changes populated, content is omitted).
Unique identifier for the comment.
The text content of the comment.
The UUID of the employee who authored the comment.
The full name of the employee who authored the comment.
The date and time the comment was created in RFC 3339 format.
The date and time the comment was last updated in RFC 3339 format.
The check-in update associated with this comment. Omitted for plain text comments.
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/goals/:goal_id/comments" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc", "creator_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "creator_name": "Jane Smith", "created_at": "2026-06-01T14:30:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00", "checkin_changes": { "target_type": "key_result", "title": "Increase NPS score to 70", "health_status": { "from": "making_progress", "to": "on_track" }, "metric": { "from": 55, "to": 68, "unit_type": "numerical" } } }, { "id": "d2e3f4a5-b6c7-8901-defa-234567890bcd", "content": "Great progress this quarter, keep it up!", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "created_at": "2026-05-28T10:00:00+00:00", "updated_at": "2026-05-28T10:00:00+00:00" }, { "id": "e3f4a5b6-c7d8-9012-efab-345678901cde", "creator_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "creator_name": "Alice Chen", "created_at": "2026-05-20T09:00:00+00:00", "updated_at": "2026-05-20T09:00:00+00:00", "checkin_changes": { "target_type": "key_result", "title": "Increase employee engagement score to 80%", "metric": { "from": 72.5, "to": 78, "unit_type": "percentage", "unit": "%" } } }, { "id": "f4a5b6c7-d8e9-0123-fabc-456789012def", "creator_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "creator_name": "Jane Smith", "created_at": "2026-05-15T11:00:00+00:00", "updated_at": "2026-05-15T11:00:00+00:00", "checkin_changes": { "target_type": "key_result", "title": "Increase quarterly revenue", "health_status": { "from": "off_track", "to": "making_progress" }, "metric": { "from": 800000, "to": 950000, "unit_type": "currency", "unit": "AUD" } } } ], "page_index": 1, "item_per_page": 20, "total_items": 4, "total_pages": 1 }}This endpoint retrieves a paginated list of key results for a goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_resultsPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to retrieve key results for.
Query Parameters
Filter key results by status.
Filter by health status.
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of key results for the goal, ordered by creation date ascending. Each entry is a separate key result object. If there are no more key results, the resulting array will be empty.
Unique identifier for the key result.
The name of the key result.
The unit type used to measure this key result.
The display unit symbol (e.g. % or a currency code like AUD). Only present when unit_type is percentage or currency.
The starting value of the key result.
The target value to achieve.
The current value of the key result. Omitted when no check-in has been recorded.
The due date of the key result in ISO 8601 format (YYYY-MM-DD).
The health status of the key result. Omitted when no status has been set.
Whether the key result is active or archived.
The percentage completion of the key result (0 to 100), rounded to two decimal places.
The UUID of the employee who owns the key result. Omitted when no owner is set.
The full name of the employee who owns the key result. Omitted when no owner is set.
The UUID of the employee who created the key result. Omitted when no creator is recorded.
The full name of the employee who created the key result. Omitted when no creator is recorded.
The UUID of the goal this key result belongs to.
The name of the goal this key result belongs to.
Employees collaborating on this key result.
The date and time the key result was created in RFC 3339 format.
The date and time the key result 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/goals/:goal_id/key_results" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "k1r2s3t4-u5v6-7890-klmn-op1234567890", "name": "Increase NPS score to 70", "unit_type": "numerical", "start_value": 45, "target_value": 70, "current_value": 60, "due_date": "2026-12-31", "health_status": "on_track", "status": "active", "progress": 60, "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "goal_name": "Improve customer satisfaction to 90%", "collaborators": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }, { "id": "l2m3n4o5-p6q7-8901-lmno-pq2345678901", "name": "Increase employee engagement score to 80%", "unit_type": "percentage", "unit": "%", "start_value": 65, "target_value": 80, "current_value": 72.5, "due_date": "2026-09-30", "health_status": "making_progress", "status": "active", "progress": 50, "owner_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "owner_name": "Alice Chen", "creator_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "creator_name": "Alice Chen", "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "goal_name": "Improve customer satisfaction to 90%", "collaborators": [ { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "name": "Jane Smith" } ], "created_at": "2026-02-01T10:00:00+00:00", "updated_at": "2026-06-01T11:15:00+00:00" }, { "id": "m3n4o5p6-q7r8-9012-mnop-qr3456789012", "name": "Launch product in two new markets", "start_value": 0, "target_value": 2, "status": "active", "progress": 0, "goal_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "goal_name": "Launch APAC expansion into three new markets", "collaborators": [], "created_at": "2026-03-01T08:00:00+00:00", "updated_at": "2026-03-01T08:00:00+00:00" } ], "page_index": 1, "item_per_page": 20, "total_items": 3, "total_pages": 1 }}This endpoint retrieves the full details of a single key result for a goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_idPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal the key result belongs to.
The UUID of the key result to retrieve.
Response Body
Unique identifier for the key result.
The name of the key result.
The unit type used to measure this key result.
The display unit symbol (e.g. % or a currency code like AUD). Only present when unit_type is percentage or currency.
The starting value of the key result.
The target value to achieve.
The current value of the key result. Omitted when no check-in has been recorded.
The due date of the key result in ISO 8601 format (YYYY-MM-DD).
The health status of the key result. Omitted when no status has been set.
Whether the key result is active or archived.
The percentage completion of the key result (0 to 100), rounded to two decimal places.
The UUID of the employee who owns the key result. Omitted when no owner is set.
The full name of the employee who owns the key result. Omitted when no owner is set.
The UUID of the employee who created the key result. Omitted when no creator is recorded.
The full name of the employee who created the key result. Omitted when no creator is recorded.
The UUID of the goal this key result belongs to.
The name of the goal this key result belongs to.
Employees collaborating on this key result.
The date and time the key result was created in RFC 3339 format.
The date and time the key result was last updated in RFC 3339 format.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "l2m3n4o5-p6q7-8901-lmno-pq2345678901", "name": "Increase employee engagement score to 80%", "unit_type": "percentage", "unit": "%", "start_value": 65, "target_value": 80, "current_value": 72.5, "due_date": "2026-09-30", "health_status": "making_progress", "status": "active", "progress": 50, "owner_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "owner_name": "Alice Chen", "creator_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "creator_name": "Alice Chen", "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "goal_name": "Improve customer satisfaction to 90%", "collaborators": [ { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "name": "Jane Smith" } ], "created_at": "2026-02-01T10:00:00+00:00", "updated_at": "2026-06-01T11:15:00+00:00" }}This endpoint creates a new key result under a goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_resultsPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to create the key result under.
Request Body
The name of the key result.
A longer description providing context for the key result.
The unit type used to measure progress. Determines how start_value, target_value, and check-in values are interpreted.
numerical— a plain numberpercentage— a percentage from 0-100monetary— a currency amount; requiressub_unitcomplete— a boolean-style 0/1 completion marker
The ISO currency code (e.g. AUD, USD) used to display the value. Required when unit is monetary.
The starting value of the key result. Must differ from target_value.
The target value to achieve. Must differ from start_value.
The due date of the key result in ISO 8601 format (YYYY-MM-DD). Must be a future date, and cannot be after the due date of the parent goal.
The UUID of the employee who owns this key result.
The UUIDs of employees collaborating on this key result.
Response Body
Returns the newly created key result.
Unique identifier for the key result.
The name of the key result.
The unit type used to measure this key result.
The display unit symbol (e.g. % or a currency code like AUD). Only present when unit_type is percentage or currency.
The starting value of the key result.
The target value to achieve.
The current value of the key result. Omitted when no check-in has been recorded.
The due date of the key result in ISO 8601 format (YYYY-MM-DD).
The health status of the key result. Omitted when no status has been set.
Whether the key result is active or archived.
The percentage completion of the key result (0 to 100), rounded to two decimal places.
The UUID of the employee who owns the key result. Omitted when no owner is set.
The full name of the employee who owns the key result. Omitted when no owner is set.
The UUID of the employee who created the key result. Omitted when no creator is recorded.
The full name of the employee who created the key result. Omitted when no creator is recorded.
The UUID of the goal this key result belongs to.
The name of the goal this key result belongs to.
Employees collaborating on this key result.
The date and time the key result was created in RFC 3339 format.
The date and time the key result was last updated in RFC 3339 format.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Increase NPS score to 70", "unit": "numerical", "start_value": 45, "target_value": 70, "due_date": "2026-12-31", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "collaborators": [] }'Response
{ "data": { "id": "k1r2s3t4-u5v6-7890-klmn-op1234567890", "name": "Increase NPS score to 70", "unit_type": "numerical", "start_value": 45, "target_value": 70, "current_value": 60, "due_date": "2026-12-31", "health_status": "on_track", "status": "active", "progress": 60, "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "goal_name": "Improve customer satisfaction to 90%", "collaborators": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }}This endpoint updates an existing key result. All fields are optional — only the fields provided are updated.
Progress is not editable here
current_value cannot be changed via this endpoint. Progress is recorded
through the check-in flow instead.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_idPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal the key result belongs to.
The UUID of the key result to update.
Request Body
The name of the key result.
A longer description providing context for the key result.
The unit type used to measure progress. Determines how start_value, target_value, and check-in values are interpreted.
numerical— a plain numberpercentage— a percentage from 0-100monetary— a currency amount; requiressub_unitcomplete— a boolean-style 0/1 completion marker
The ISO currency code (e.g. AUD, USD) used to display the value.
The starting value of the key result. Must differ from the effective target_value.
The target value to achieve. Must differ from the effective start_value.
The due date of the key result in ISO 8601 format (YYYY-MM-DD). Must be a future date, and cannot be after the due date of the parent goal.
The UUID of the employee who owns this key result.
The UUIDs of employees collaborating on this key result. This is a full replacement of the existing collaborators list.
Not updatable via this endpoint — use the check-in flow to record progress. Including this field returns a 422 error.
Response Body
Returns the updated key result.
Unique identifier for the key result.
The name of the key result.
The unit type used to measure this key result.
The display unit symbol (e.g. % or a currency code like AUD). Only present when unit_type is percentage or currency.
The starting value of the key result.
The target value to achieve.
The current value of the key result. Omitted when no check-in has been recorded.
The due date of the key result in ISO 8601 format (YYYY-MM-DD).
The health status of the key result. Omitted when no status has been set.
Whether the key result is active or archived.
The percentage completion of the key result (0 to 100), rounded to two decimal places.
The UUID of the employee who owns the key result. Omitted when no owner is set.
The full name of the employee who owns the key result. Omitted when no owner is set.
The UUID of the employee who created the key result. Omitted when no creator is recorded.
The full name of the employee who created the key result. Omitted when no creator is recorded.
The UUID of the goal this key result belongs to.
The name of the goal this key result belongs to.
Employees collaborating on this key result.
The date and time the key result was created in RFC 3339 format.
The date and time the key result was last updated in RFC 3339 format.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "target_value": 80, "due_date": "2026-09-30" }'Response
{ "data": { "id": "l2m3n4o5-p6q7-8901-lmno-pq2345678901", "name": "Increase employee engagement score to 80%", "unit_type": "percentage", "unit": "%", "start_value": 65, "target_value": 80, "current_value": 72.5, "due_date": "2026-09-30", "health_status": "making_progress", "status": "active", "progress": 50, "owner_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "owner_name": "Alice Chen", "creator_id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "creator_name": "Alice Chen", "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "goal_name": "Improve customer satisfaction to 90%", "collaborators": [ { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "name": "Jane Smith" } ], "created_at": "2026-02-01T10:00:00+00:00", "updated_at": "2026-06-01T11:15:00+00:00" }}This endpoint permanently deletes a key result.
Irreversible
This action cannot be undone. The key result cannot be recovered after deletion.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_idPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal the key result belongs to.
The UUID of the key result to delete.
Response Body
Returns HTTP 204 No Content on success. No response body is included.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
This endpoint archives or unarchives a key result. Archiving a key result excludes it from the parent goal's progress calculation without permanently deleting it.
Idempotent
Archiving an already-archived key result, or unarchiving an already-active key result, returns HTTP 200 with no error.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id/archive_statusPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal the key result belongs to.
The UUID of the key result to archive or unarchive.
Request Body
The desired archive state of the key result. Use archived to archive the key result, or active to unarchive it.
Response Body
true when the archive status was updated successfully.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id/archive_status" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "status": "archived" }'Response
{ "data": { "success": true }}This endpoint records a check-in on a key result, updating its current value and health status.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id/statusPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal the key result belongs to.
The UUID of the key result to check in on.
Request Body
The new current value for the key result. For key results using the complete unit type, only 0 or 1 is accepted.
The health status to record for this check-in. Allowed values: on_track, making_progress, off_track.
An optional comment to include with the check-in. Maximum 5,000 characters.
Response Body
Returns HTTP 200 with the updated key result on success.
Unique identifier for the key result.
The name of the key result.
The unit type used to measure this key result.
The display unit symbol (e.g. % or a currency code like AUD). Only present when unit_type is percentage or currency.
The starting value of the key result.
The target value to achieve.
The current value of the key result. Omitted when no check-in has been recorded.
The due date of the key result in ISO 8601 format (YYYY-MM-DD).
The health status of the key result. Omitted when no status has been set.
Whether the key result is active or archived.
The percentage completion of the key result (0 to 100), rounded to two decimal places.
The UUID of the employee who owns the key result. Omitted when no owner is set.
The full name of the employee who owns the key result. Omitted when no owner is set.
The UUID of the employee who created the key result. Omitted when no creator is recorded.
The full name of the employee who created the key result. Omitted when no creator is recorded.
The UUID of the goal this key result belongs to.
The name of the goal this key result belongs to.
Employees collaborating on this key result.
The date and time the key result was created in RFC 3339 format.
The date and time the key result was last updated in RFC 3339 format.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/key_results/:key_result_id/status" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "current_value": 60, "health_status": "on_track", "comment": "Behind schedule due to resource constraints in Q2." }'Response
{ "data": { "id": "k1r2s3t4-u5v6-7890-klmn-op1234567890", "name": "Increase NPS score to 70", "unit_type": "numerical", "start_value": 45, "target_value": 70, "current_value": 60, "due_date": "2026-12-31", "health_status": "on_track", "status": "active", "progress": 60, "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "goal_name": "Improve customer satisfaction to 90%", "collaborators": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }}This endpoint archives or unarchives a goal. Archiving a goal removes it from active views without permanently deleting it. Key results belonging to the goal are not affected.
Idempotent
Archiving an already-archived goal, or unarchiving an already-active goal, returns HTTP 200 with no error.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/archive_statusPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to archive or unarchive.
Request Body
The desired archive state of the goal. Use archived to archive the goal, or active to unarchive it.
An optional reason for archiving the goal. When provided, the reason is recorded as a comment on the goal. Ignored when status is active.
Response Body
true when the archive status was updated successfully.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/archive_status" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "status": "archived", "reason": "Goal superseded by Q3 strategy" }'Response
{ "data": { "success": true }}This endpoint records a health-status check-in on a goal. Every successful call creates an activity entry visible in the goal's feed, regardless of whether the health status changed.
Activity always recorded
Unlike a manual check-in in the platform, every API call records an activity entry — even if the health status is unchanged. This ensures integrations always produce a visible audit trail.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/statusPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to check in on.
Request Body
The health status to record for this check-in. Allowed values: on_track, making_progress, off_track.
An optional comment to include with the check-in. Maximum 5,000 characters.
Response Body
Returns HTTP 200 with the updated goal on success.
Unique identifier for the goal.
The name of the goal.
The type of the goal.
The description of the goal.
The UUID of the employee who owns the goal.
The full name of the employee who owns the goal.
The UUID of the employee who created the goal.
The full name of the employee who created the goal.
The due date of the goal in ISO 8601 format (YYYY-MM-DD).
The health status of the goal.
Who can see the goal. everyone is visible to all organisation members; participants is visible only to the owner and key result collaborators; groups is visible only to members of the associated group (only valid for goal_type=group).
The UUID of the parent goal this goal is aligned to.
The name of the parent goal this goal is aligned to.
Whether progress on this goal feeds into the parent goal's progress.
The UUID of the group associated with this goal. Only populated for goal_type=group.
The name of the group associated with this goal. Only populated for goal_type=group.
Whether the goal is active or archived.
The percentage completion of the goal (0 to 100), rounded to two decimal places.
The number of active key results on this goal.
The number of active child goals aligned to this goal.
Files attached to the goal.
The date and time the goal was created in RFC 3339 format.
The date and time the goal was last updated in RFC 3339 format.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id/status" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "health_status": "on_track", "comment": "Behind schedule due to resource constraints in Q2." }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Improve customer satisfaction to 90%", "goal_type": "company", "description": "Drive NPS and CSAT scores by improving product quality and support response times.", "owner_id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "owner_name": "Jane Smith", "creator_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "creator_name": "John Doe", "due_date": "2026-12-31", "health_status": "on_track", "visibility_type": "everyone", "parent_id": null, "parent_name": null, "feed_to_parent": false, "group_id": null, "group_name": null, "status": "active", "progress": 62.5, "key_results_count": 3, "children_count": 2, "attachments": [], "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-06-01T14:30:00+00:00" }}This endpoint permanently deletes a goal. All of the goal's key results are permanently deleted along with it. Child goals aligned to the deleted goal are not deleted — they become root-level goals with no parent.
Irreversible
This action cannot be undone. The goal and its key results cannot be recovered after deletion.
Requires the Goals - Delete scope, and either the Goals and OKRs Delete permission for the goal's type, or that the caller is the owner or creator of the goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_idPath Parameters
The UUID of the organisation the goal belongs to.
The UUID of the goal to delete.
Response Body
Returns HTTP 204 No Content on success. No response body is included.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/:goal_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
Upload files for use as goal attachments. The returned file ids can then be passed as attachment_ids when creating or updating a goal.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/goals/file_uploadsPath Parameters
The ID of the organisation
Request Body
Files to upload via multipart/form-data.
Note
Allowed formats: JPG, JPEG, PNG, PDF, DOC, DOCX.
Response Body
Returns a list of successfully uploaded file details on HTTP 201.
List of uploaded file details
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/goals/file_uploads" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "files=/path/to/receipt.pdf"Response
{ "data": { "files": [ { "id": "c580adfd-c0f6-4544-85a8-b366c4c79251", "url": "https://cdn.employmenthero.com/files/goal-attachment.pdf", "name": "goal-attachment.pdf" } ] }}