Compliance Document Tag

List Compliance Document Tags

Returns all compliance document tags belonging to the organisation. Active tags are returned by default; pass include_archived=true to include archived tags in the response.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

Query Parameters

include_archivedboolean

When true, includes archived tags alongside active tags in the response. Defaults to false.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

Returns a paginated list of compliance document tags for the organisation. Active tags are returned by default; pass include_archived=true to include archived tags.

dataobject

itemsobject[]

iduuid

The unique identifier of the compliance document tag.

namestring

The display name of the compliance document tag.

archived_atdatetime

The timestamp when the tag was archived. Null when the tag is active.

created_atdatetime

The timestamp when the tag was created.

updated_atdatetime

The timestamp when the tag was last updated.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "items": [      {        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",        "name": "Privacy Policy",        "archived_at": null,        "created_at": "2025-05-01T09:00:00.000Z",        "updated_at": "2025-05-01T09:00:00.000Z"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Create Compliance Document Tag

Creates a new compliance document tag for the organisation. Tag names must be unique within an organisation (matched case-insensitively). The tag is immediately available for use on document uploads once created.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

Request Body

namestringrequired

The name of the compliance document tag. Must be unique within the organisation (case-insensitive).

Response Body

Returns HTTP 201 Created with the newly created compliance document tag.

dataobject

iduuid

The unique identifier of the compliance document tag.

namestring

The display name of the compliance document tag.

archived_atdatetime

The timestamp when the tag was archived. Null when the tag is active.

created_atdatetime

The timestamp when the tag was created.

updated_atdatetime

The timestamp when the tag was last updated.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Right to Work"  }'

Response

{  "data": {    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "name": "Privacy Policy",    "archived_at": null,    "created_at": "2025-05-01T09:00:00.000Z",    "updated_at": "2025-05-01T09:00:00.000Z"  }}

Rename Compliance Document Tag

Renames an existing compliance document tag. The new name must be unique within the organisation (case-insensitive). Archived tags cannot be renamed; attempting to do so returns 422 Unprocessable Entity.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags/:tag_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

tag_iduuidrequired

The ID of the compliance document tag to rename.

Request Body

namestringrequired

The new name for the compliance document tag. Must be unique within the organisation (case-insensitive).

Response Body

Returns HTTP 200 OK with the updated compliance document tag.

dataobject

iduuid

The unique identifier of the compliance document tag.

namestring

The display name of the compliance document tag.

archived_atdatetime

The timestamp when the tag was archived. Null when the tag is active.

created_atdatetime

The timestamp when the tag was created.

updated_atdatetime

The timestamp when the tag was last updated.

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags/:tag_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Safety Certificate"  }'

Response

{  "data": {    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "name": "Privacy Policy",    "archived_at": null,    "created_at": "2025-05-01T09:00:00.000Z",    "updated_at": "2025-05-01T09:00:00.000Z"  }}

Archive Compliance Document Tag

Archives a compliance document tag, excluding it from future document tagging operations. Existing document associations are preserved. Archiving is permanent in v1 — there is no unarchive endpoint. Calling this endpoint on an already-archived tag is idempotent.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags/:tag_id/archive

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

tag_iduuidrequired

The ID of the compliance document tag to archive.

Response Body

Returns HTTP 204 No Content on success. No response body is included. Archiving an already-archived tag is idempotent and also returns 204.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/compliance_document_tags/:tag_id/archive" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

This endpoint does not return a response body.