Department

Get Departments

Retrieve a paginated list of departments for an organisation, across all work sites and including both active and disabled departments. Requires the Departments View permission (or admin/owner access).

GET

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

Path Parameters

organisation_iduuidrequired

The ID of the organisation

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A paginated list of departments for the organisation.

dataobject

itemsobject[]

iduuid

Unique identifier for the object.

namestring

The name of the department.

statusenum<string>

Whether the department is active or disabled.

assignment_countnumber

The number of employees assigned to this department.

notification_settingsobject

Notification settings for this department.

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/departments" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "items": [      {        "id": "5b7cf013-9c7c-417b-abd7-ca1d5a8eb313",        "name": "Engineering Department",        "status": "active",        "assignment_count": 2,        "notification_settings": {          "check_in_time": "09:00 AM",          "check_out_time": "05:00 PM",          "days_of_week": [            "Monday",            "Tuesday",            "Wednesday"          ]        }      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Get Department

Retrieve a single department by its identifier, whether it is active or disabled. Requires the Departments View permission (or admin/owner access).

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

department_iduuidrequired

The ID of the department

Response Body

The requested department object.

dataobject

iduuid

Unique identifier for the object.

namestring

The name of the department.

statusenum<string>

Whether the department is active or disabled.

assignment_countnumber

The number of employees assigned to this department.

notification_settingsobject

Notification settings for this department.

Example

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

Response

{  "data": {    "id": "5b7cf013-9c7c-417b-abd7-ca1d5a8eb313",    "name": "Engineering Department",    "status": "active",    "assignment_count": 2,    "notification_settings": {      "check_in_time": "09:00 AM",      "check_out_time": "05:00 PM",      "days_of_week": [        "Monday",        "Tuesday",        "Wednesday"      ]    }  }}

Create Department

Create a new department for a work site. The department can include notification settings for clock-in and clock-out times, and can have specific members assigned to it.

POST

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

Path Parameters

organisation_iduuidrequired

The ID of the organisation

Request Body

work_site_iduuidrequired

UUID of an existing work site

namestringrequired

Department name

clock_in_timestring

Clock-in time (e.g., "09:00", "9:00 AM")

clock_out_timestring

Clock-out time (e.g., "17:00", "5:00 PM")

days_appliedenum<string>[]

Days of week

member_idsuuid[]

Array of member UUIDs to assign to the department

Response Body

The created department object.

dataobject

iduuid

Unique identifier for the object.

namestring

The name of the department.

statusenum<string>

Whether the department is active or disabled.

assignment_countnumber

The number of employees assigned to this department.

notification_settingsobject

Notification settings for this department.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "work_site_id": "bdf48551-d061-45d2-b30f-9d78279f0707",    "name": "Engineering Department",    "clock_in_time": "09:00",    "clock_out_time": "17:00",    "days_applied": [      "Monday",      "Tuesday",      "Wednesday"    ],    "member_ids": [      "5388432b-2aa1-46b3-ad8c-f7c46356bb56",      "032de036-9597-4119-be86-8602c3e2e363"    ]  }'

Response

{  "data": {    "id": "5b7cf013-9c7c-417b-abd7-ca1d5a8eb313",    "name": "Engineering Department",    "status": "active",    "assignment_count": 2,    "notification_settings": {      "check_in_time": "09:00 AM",      "check_out_time": "05:00 PM",      "days_of_week": [        "Monday",        "Tuesday",        "Wednesday"      ]    }  }}

Update Department

Update an existing department. You can modify the department name, notification settings for clock-in and clock-out times, and manage member assignments by adding or removing members from the department.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

department_iduuidrequired

The ID of the department

Request Body

namestring

Department name

clock_in_timestring

Clock-in time (e.g., "09:00", "9:00 AM")

clock_out_timestring

Clock-out time (e.g., "17:00", "5:00 PM")

days_appliedenum<string>[]

Days of week

member_idsuuid[]

Array of member UUIDs to assign to the department

Response Body

The updated department object.

dataobject

iduuid

Unique identifier for the object.

namestring

The name of the department.

statusenum<string>

Whether the department is active or disabled.

assignment_countnumber

The number of employees assigned to this department.

notification_settingsobject

Notification settings for this department.

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Engineering Department",    "clock_in_time": "09:00",    "clock_out_time": "17:00",    "days_applied": [      "Monday",      "Tuesday",      "Wednesday"    ],    "member_ids": [      "5388432b-2aa1-46b3-ad8c-f7c46356bb56",      "032de036-9597-4119-be86-8602c3e2e363"    ]  }'

Response

{  "data": {    "id": "5b7cf013-9c7c-417b-abd7-ca1d5a8eb313",    "name": "Engineering Department",    "status": "active",    "assignment_count": 2,    "notification_settings": {      "check_in_time": "09:00 AM",      "check_out_time": "05:00 PM",      "days_of_week": [        "Monday",        "Tuesday",        "Wednesday"      ]    }  }}

Disable Department

Disable a department by setting its status to disabled. This request takes no body and is idempotent: calling it on a department that is already disabled succeeds and returns the department unchanged. Requires the Departments Modify permission (or admin/owner access).

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id/disable

Path Parameters

organisation_iduuidrequired

The ID of the organisation

department_iduuidrequired

The ID of the department

Response Body

The department with its updated status.

dataobject

iduuid

Unique identifier for the object.

namestring

The name of the department.

statusenum<string>

Whether the department is active or disabled.

assignment_countnumber

The number of employees assigned to this department.

notification_settingsobject

Notification settings for this department.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id/disable" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "id": "5b7cf013-9c7c-417b-abd7-ca1d5a8eb313",    "name": "Engineering Department",    "status": "active",    "assignment_count": 2,    "notification_settings": {      "check_in_time": "09:00 AM",      "check_out_time": "05:00 PM",      "days_of_week": [        "Monday",        "Tuesday",        "Wednesday"      ]    }  }}

Enable Department

Enable a department by setting its status to active. This request takes no body and is idempotent: calling it on a department that is already active succeeds and returns the department unchanged. Requires the Departments Modify permission (or admin/owner access).

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id/enable

Path Parameters

organisation_iduuidrequired

The ID of the organisation

department_iduuidrequired

The ID of the department

Response Body

The department with its updated status.

dataobject

iduuid

Unique identifier for the object.

namestring

The name of the department.

statusenum<string>

Whether the department is active or disabled.

assignment_countnumber

The number of employees assigned to this department.

notification_settingsobject

Notification settings for this department.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/departments/:department_id/enable" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "id": "5b7cf013-9c7c-417b-abd7-ca1d5a8eb313",    "name": "Engineering Department",    "status": "active",    "assignment_count": 2,    "notification_settings": {      "check_in_time": "09:00 AM",      "check_out_time": "05:00 PM",      "days_of_week": [        "Monday",        "Tuesday",        "Wednesday"      ]    }  }}