Employment HeroThis endpoint retrieves a list of all policies for a specific organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policiesPath Parameters
The ID of the organisation to retrieve
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 policy records. Each entry in the array is a separate policy object. If there is no more policies, the resulting array will be empty.
The policy id
The name of policy
Determine policy is mandatory or not
Time at which the policy was created
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/policies" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "1d25a390-7b0e-0135-0209-061f87a4b1b6", "name": "Wonderful Company - Full-Disk Encryption Policy", "induction": true, "created_at": "2017-09-14T10:03:51+10:00" }, { "id": "91216a90-f3cb-0133-ec72-4a8f8c38fb42", "name": "Wonderful Company - Working From Home Agreement", "induction": false, "created_at": "2016-05-04T12:12:25+10:00" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}Retrieve the full details of a single policy by its UUID. The response includes sharing configuration, responsible owner, and timestamps.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_idPath Parameters
The ID of the organisation.
The ID of the policy to retrieve.
Response Body
The full policy object for the requested policy ID.
Unique identifier of the policy.
Name of the policy.
Publication status of the policy.
Whether acknowledgement of this policy is mandatory for assigned members.
Whether the policy is archived.
Whether the policy content is an uploaded document.
How often members must acknowledge the policy: one_off (once) or yearly (every year).
Due date configuration for this policy.
Full sharing configuration — which member types, members, teams, locations, and employing entities this policy is assigned to.
Member responsible for maintaining this policy.
ISO 8601 timestamp when the policy was created.
ISO 8601 timestamp when the policy was last updated.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Full-Disk Encryption Policy", "status": "Published", "induction": true, "archived": false, "uploaded_policy": true, "renewal_type": "yearly", "due_date_setting": null, "shared_to": { "all_employees": true, "all_contractors": false, "all_volunteers": false, "member_ids": [], "group_ids": [], "location_ids": [], "employing_entity_ids": [] }, "responsible_owner": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Jane Smith" }, "created_at": "2025-01-15T09:00:00.000Z", "updated_at": "2025-06-01T14:30:00.000Z" }}Upload a file and create a new policy for the organisation in Draft status. The policy is not assigned to any members until you call the Share endpoint.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policiesPath Parameters
The ID of the organisation.
Request Body
Name of the policy. Must be unique within the organisation.
Policy document to upload. Accepted formats: .pdf, .doc, .docx, .png. Maximum size: 10 MB.
Whether acknowledgement is mandatory for assigned members. Defaults to false.
Response Body
The newly created policy object in Draft status with no members assigned yet.
Unique identifier of the policy.
Name of the policy.
Publication status of the policy.
Whether acknowledgement of this policy is mandatory for assigned members.
Whether the policy is archived.
Whether the policy content is an uploaded document.
How often members must acknowledge the policy: one_off (once) or yearly (every year).
Due date configuration for this policy.
Full sharing configuration — which member types, members, teams, locations, and employing entities this policy is assigned to.
Member responsible for maintaining this policy.
ISO 8601 timestamp when the policy was created.
ISO 8601 timestamp when the policy was last updated.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "name=Remote Work Policy" \ -F "file=@(binary file)" \ -F "induction=false"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Remote Work Policy", "status": "Draft", "induction": false, "archived": false, "uploaded_policy": true, "renewal_type": "one_off", "due_date_setting": null, "shared_to": { "all_employees": false, "all_contractors": false, "all_volunteers": false, "member_ids": [], "group_ids": [], "location_ids": [], "employing_entity_ids": [] }, "responsible_owner": null, "created_at": "2025-06-01T14:30:00.000Z", "updated_at": "2025-06-01T14:30:00.000Z" }}Archive a policy. Archiving does not change the publication status — a Published policy remains Published. This operation is idempotent: archiving an already-archived policy returns 200 with no error.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_id/archivePath Parameters
The ID of the organisation.
The ID of the policy to archive.
Response Body
The updated policy object with archived set to true. Idempotent — archiving an already-archived policy returns 200 with no error.
Unique identifier of the policy.
Name of the policy.
Publication status of the policy.
Whether acknowledgement of this policy is mandatory for assigned members.
Whether the policy is archived.
Whether the policy content is an uploaded document.
How often members must acknowledge the policy: one_off (once) or yearly (every year).
Due date configuration for this policy.
Full sharing configuration — which member types, members, teams, locations, and employing entities this policy is assigned to.
Member responsible for maintaining this policy.
ISO 8601 timestamp when the policy was created.
ISO 8601 timestamp when the policy was last updated.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_id/archive" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Full-Disk Encryption Policy", "status": "Published", "induction": true, "archived": true, "uploaded_policy": true, "renewal_type": "yearly", "due_date_setting": null, "shared_to": { "all_employees": true, "all_contractors": false, "all_volunteers": false, "member_ids": [], "group_ids": [], "location_ids": [], "employing_entity_ids": [] }, "responsible_owner": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Jane Smith" }, "created_at": "2025-01-15T09:00:00.000Z", "updated_at": "2025-06-01T14:30:00.000Z" }}Restore an archived policy. Returns 422 if the policy is not currently archived.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_id/unarchivePath Parameters
The ID of the organisation.
The ID of the policy to restore.
Response Body
The updated policy object with archived set to false.
Unique identifier of the policy.
Name of the policy.
Publication status of the policy.
Whether acknowledgement of this policy is mandatory for assigned members.
Whether the policy is archived.
Whether the policy content is an uploaded document.
How often members must acknowledge the policy: one_off (once) or yearly (every year).
Due date configuration for this policy.
Full sharing configuration — which member types, members, teams, locations, and employing entities this policy is assigned to.
Member responsible for maintaining this policy.
ISO 8601 timestamp when the policy was created.
ISO 8601 timestamp when the policy was last updated.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_id/unarchive" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Full-Disk Encryption Policy", "status": "Published", "induction": true, "archived": false, "uploaded_policy": true, "renewal_type": "yearly", "due_date_setting": null, "shared_to": { "all_employees": true, "all_contractors": false, "all_volunteers": false, "member_ids": [], "group_ids": [], "location_ids": [], "employing_entity_ids": [] }, "responsible_owner": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Jane Smith" }, "created_at": "2025-01-15T09:00:00.000Z", "updated_at": "2025-06-01T14:30:00.000Z" }}Permanently delete a policy. Both Draft and Published policies can be deleted. Returns 422 if any member has acknowledged the policy.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_idPath Parameters
The ID of the organisation.
The ID of the policy to permanently delete.
Response Body
Returns HTTP 204 No Content on success. The policy is permanently deleted and cannot be recovered.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies/:policy_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
Query the policy compliance report across the organisation. Returns a paginated list of member–policy pairs with their acknowledgement status. Supports filtering by status, specific policies, members, groups, or work locations, passed as query parameters (for example group_ids[]=<uuid>).
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/acknowledgementsPath Parameters
The ID of the organisation.
Query Parameters
Current page index
11Number of items per page
20100Filter by acknowledgement status. Omit to return all three statuses.
Limit results to specific policy UUIDs. Maximum 30.
Limit results to specific member UUIDs. Maximum 30.
Filter by group UUIDs. Maximum 30.
Filter by work location UUIDs. Maximum 30.
Response Body
A paginated list of member–policy acknowledgement records matching the supplied filters.
UUID of the policy.
Name of the policy.
UUID of the member.
Display name of the member.
Acknowledgement status of this member–policy pair.
ISO 8601 timestamp when the member acknowledged the policy.
Due date for acknowledgement in YYYY-MM-DD 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/policies/acknowledgements" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "policy_name": "Full-Disk Encryption Policy", "member_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "member_name": "Alex Johnson", "status": "acknowledged", "acknowledged_at": "2025-05-20T08:45:00.000Z", "due_date": "2025-06-01" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Sends acknowledgement reminder emails for specific member–policy pairs. Each pair comes back with a status:
queued: a reminder email was sent to the member.skipped: no email was sent, andreasonsays why:not_assigned: the policy isn't assigned to the member.already_acknowledged: the member has already acknowledged the policy.recently_reminded: the member was already reminded about this policy in the last 24 hours.
failed: the reminder couldn't be queued for this pair, andreasonisinternal_error. Other pairs in the request are still processed, and it's safe to retry the failed pair.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/remindPath Parameters
The ID of the organisation.
Request Body
One or more policy–member pairs to send reminders for. Maximum 100.
Response Body
Returns HTTP 202 Accepted with one result per policy–member pair, showing whether a reminder email was queued, skipped or failed and, if skipped, why.
One result per unique policy–member pair, in request order. A pair sent more than once in the request is returned once.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies/remind" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "d4e5f6a7-b8c9-0123-defa-234567890123" } ] }'Response
{ "data": { "items": [ { "policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "d4e5f6a7-b8c9-0123-defa-234567890123", "status": "queued", "reason": null }, { "policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "e5f6a7b8-c9d0-1234-efab-345678901234", "status": "skipped", "reason": "already_acknowledged" } ] }}Queue acknowledgement reminder emails for all outstanding or overdue members across the organisation. Optionally filter to specific policies or a specific acknowledgement state. Returns immediately — reminders are processed asynchronously in the background. Members who were already reminded about a policy in the last 24 hours, through this endpoint or Remind Policy, aren't emailed again for that policy.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policies/remind_allPath Parameters
The ID of the organisation.
Request Body
Limit reminders to specific policy UUIDs. Omit to include all active policies. Maximum 100.
Filter members by acknowledgement state. Omit to remind both outstanding and overdue members.
Response Body
Returns HTTP 202 Accepted on success. No response body is included. Reminder emails are sent to the matching outstanding and overdue members shortly afterwards.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies/remind_all" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "policy_ids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "status": "outstanding" }'Response
This endpoint does not return a response body.