Cost Centre

Get Cost Centres

This endpoint retrieves a paginated list of cost centres available within the specified organisation.

GET

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

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A JSON object with a data property that contains an array of cost centre objects and pagination information. Each cost centre object includes the unique identifier and name of the cost centre.

dataobject

itemsobject[]

iduuid

Unique identifier for the cost centre.

namestring

Name of the cost centre.

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

Response

{  "data": {    "items": [      {        "id": "7daf1397-338c-4b91-9d46-44e6cd56297a",        "name": "Marketing Department"      },      {        "id": "b992fc49-7e98-4743-b53b-51bec9cf4dc3",        "name": "Sales Department"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 2,    "total_pages": 1  }}

Update Cost Centre

This endpoint updates the name and/or parent of a cost centre. Setting parent_id moves the cost centre within the cost centre hierarchy.

Requirements

Requires the Cost Centres - Update OAuth scope and the Cost Centres permissions module permission. This endpoint is not available to KeyPay-connected organisations, where cost centres are managed in KeyPay and are read-only in Employment Hero. Write requests are limited to 10 per 60 seconds per organisation.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centres/:cost_centre_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation the cost centre belongs to.

cost_centre_iduuidrequired

The ID of the cost centre to update.

Request Body

namestring

The new name for the cost centre. Cannot be blank. If the cost centre is enabled, the name must not match another enabled cost centre in the organisation.

parent_iduuid

The ID of the new parent cost centre. Set to null to move the cost centre to the root level. The parent must be an enabled cost centre in the same organisation and cannot be the cost centre itself or one of its descendants. Empty strings are rejected.

Response Body

Returns the updated cost centre object, including its new parent_id, parent_name and level.

dataobject

iduuid

Unique identifier for the cost centre.

namestring

Name of the cost centre.

statusenum<string>

Whether the cost centre is enabled. Inactive cost centres are not offered as options for new assignments.

parent_iduuid

Unique identifier of the parent cost centre. Null for root-level cost centres.

parent_namestring

Name of the parent cost centre. Null for root-level cost centres.

levelinteger

Depth of the cost centre in the hierarchy. Root-level cost centres have a level of 0.

created_atdatetime

When the cost centre was created, in ISO 8601 format.

updated_atdatetime

When the cost centre was last updated, in ISO 8601 format.

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centres/:cost_centre_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Marketing Operations",    "parent_id": null  }'

Response

{  "data": {    "id": "7daf1397-338c-4b91-9d46-44e6cd56297a",    "name": "Marketing Department",    "status": "active",    "parent_id": null,    "parent_name": null,    "level": 0,    "created_at": "2025-05-01T09:00:00.000Z",    "updated_at": "2025-05-01T09:00:00.000Z"  }}

Update Cost Centre Active Status

This endpoint enables or disables a cost centre. Use it to control whether a cost centre is offered as an option for new assignments.

Requirements

This endpoint is not available to KeyPay-connected organisations, where cost centres are managed in KeyPay and are read-only in Employment Hero.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centres/:cost_centre_id/active_status

Path Parameters

organisation_iduuidrequired

The ID of the organisation the cost centre belongs to.

cost_centre_iduuidrequired

The ID of the cost centre to enable or disable.

Request Body

activebooleanrequired

true to enable the cost centre, or false to disable it. The change also applies to all descendant cost centres.

Response Body

Returns the cost centre with its updated status. Enabling or disabling also sets every descendant cost centre to the same status.

dataobject

iduuid

Unique identifier for the cost centre.

namestring

Name of the cost centre.

statusenum<string>

Whether the cost centre is enabled. Inactive cost centres are not offered as options for new assignments.

parent_iduuid

Unique identifier of the parent cost centre. Null for root-level cost centres.

parent_namestring

Name of the parent cost centre. Null for root-level cost centres.

levelinteger

Depth of the cost centre in the hierarchy. Root-level cost centres have a level of 0.

created_atdatetime

When the cost centre was created, in ISO 8601 format.

updated_atdatetime

When the cost centre was last updated, in ISO 8601 format.

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centres/:cost_centre_id/active_status" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "active": false  }'

Response

{  "data": {    "id": "7daf1397-338c-4b91-9d46-44e6cd56297a",    "name": "Marketing Department",    "status": "active",    "parent_id": null,    "parent_name": null,    "level": 0,    "created_at": "2025-05-01T09:00:00.000Z",    "updated_at": "2025-05-01T09:00:00.000Z"  }}

Delete Cost Centre

This endpoint permanently deletes a cost centre along with all of its descendant cost centres.

Note

This action cannot be undone. A cost centre cannot be deleted while it, or any of its descendants, has employees, timesheets, rostered shifts, or HR positions assigned. To keep a cost centre without deleting it, disable it with the Update Cost Centre Active Status endpoint.

Requirements

This endpoint is not available to KeyPay-connected organisations, where cost centres are managed in KeyPay and are read-only in Employment Hero.

DELETE

https://api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centres/:cost_centre_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation the cost centre belongs to.

cost_centre_iduuidrequired

The ID of the cost centre to delete. Its descendant cost centres are deleted with it.

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

Response

This endpoint does not return a response body.