Rostered Shift

Get Rostered Shifts

List all the rostered shifts accessible by current user. The result is paginated

GET

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

Path Parameters

organisation_iduuidrequired

ID of the organisation

Query Parameters

from_datestringrequired

Start date of the range in ISO-8601 format (inclusive)

to_datestringrequired

End date of the range in ISO-8601 format (inclusive)

statusesstring[]

Statuses of the rostered shifts to filter by

location_idsuuid[]

Location IDs of the rostered shifts to filter by

member_idsuuid[]

Member IDs of the rostered shifts to filter by

unassigned_shifts_onlyboolean

Whether to return only unassigned shifts

exclude_shifts_overlapping_from_dateboolean

Whether to exclude shifts that overlap with from_date.
If this flag is set to true: Retrieve the shift which start time in [from_date, to_date)
Otherwise: Retrieve the shift which start time in [from_date - 1, to_date) and end time in (from_date, to_date + 1]

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

The rostered shifts current user can access

dataobject

itemsobject[]

iduuid

ID of the rostered shift

start_timedatetime

Shift start time

end_timedatetime

Shift end time

statusstring

Status of the rostered shift

notesstring

Notes for the rostered shift

is_open_shiftboolean

Whether the shift is open

location_iduuid

ID of the location where the shift is rostered

location_namestring

Name of the location where the shift is rostered

work_site_iduuid

ID of the work site where the shift is rostered

work_site_namestring

Name of the work site where the shift is rostered

work_site_statusenum<string>

The status of the work site where the shift is rostered

position_iduuid

ID of the position for which the shift is rostered

position_namestring

Name of the position for which the shift is rostered

position_statusenum<string>

The status of the position for which the shift is rostered

member_iduuid

ID of the member rostered for the shift

member_full_namestring

Full name of the member rostered for the shift

shift_swap_cutoff_timedatetime

Time after which shift swap is not allowed

typestring

Type of the shift

work_type_iduuid

ID of the work type for the shift

work_type_namestring

Name of the work type for the shift

shift_swapobject

Details of the shift swap

breaksobject[]

Breaks during the shift

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

Response

{  "data": {    "items": [      {        "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "start_time": "2024-06-14T09:00:00.000Z",        "end_time": "2024-06-14T17:00:00.000Z",        "status": "published",        "notes": "Hello world",        "is_open_shift": false,        "location_id": "23e55174-2c7f-468d-9d11-9c387e2c3e70",        "location_name": "John Doe Hospital",        "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "work_site_name": "LA Work Site",        "work_site_status": "active",        "position_id": "032d4063-2a79-45e6-b047-5b4876b59afc",        "position_name": "Barber",        "position_status": "active",        "member_id": "6664453a-c118-48f1-897e-3df62d45bd84",        "member_full_name": "John Doe",        "shift_swap_cutoff_time": null,        "type": "RosteredShift",        "work_type_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "work_type_name": "Full time",        "shift_swap": {          "id": "d71690b7-381f-4d54-8bdc-e4fd9d3e3be1",          "requesting_shift_id": "4a35ccb6-8ff6-4719-b7fb-726b40467957",          "receiving_shift_id": "dbab7b49-b40b-4e0d-ae69-a5fde016c5c7",          "status": "awaiting_receiver",          "requesting_notes": null        },        "breaks": [          {            "start_time": "2024-06-14T12:00:00.000Z",            "end_time": "2024-06-14T13:00:00.000Z"          }        ]      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Get Rostered Shift

Get rostered shift record using its ID

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/:id

Path Parameters

organisation_iduuidrequired

ID of the organisation

iduuidrequired

ID of the rostered shift record

Response Body

The rostered shift record

dataobject

iduuid

ID of the rostered shift

start_timedatetime

Shift start time

end_timedatetime

Shift end time

statusstring

Status of the rostered shift

notesstring

Notes for the rostered shift

is_open_shiftboolean

Whether the shift is open

location_iduuid

ID of the location where the shift is rostered

location_namestring

Name of the location where the shift is rostered

work_site_iduuid

ID of the work site where the shift is rostered

work_site_namestring

Name of the work site where the shift is rostered

work_site_statusenum<string>

The status of the work site where the shift is rostered

position_iduuid

ID of the position for which the shift is rostered

position_namestring

Name of the position for which the shift is rostered

position_statusenum<string>

The status of the position for which the shift is rostered

member_iduuid

ID of the member rostered for the shift

member_full_namestring

Full name of the member rostered for the shift

shift_swap_cutoff_timedatetime

Time after which shift swap is not allowed

typestring

Type of the shift

work_type_iduuid

ID of the work type for the shift

work_type_namestring

Name of the work type for the shift

shift_swapobject

Details of the shift swap

breaksobject[]

Breaks during the shift

Example

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

Response

{  "data": {    "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",    "start_time": "2024-06-14T09:00:00.000Z",    "end_time": "2024-06-14T17:00:00.000Z",    "status": "published",    "notes": "Hello world",    "is_open_shift": false,    "location_id": "23e55174-2c7f-468d-9d11-9c387e2c3e70",    "location_name": "John Doe Hospital",    "work_site_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",    "work_site_name": "LA Work Site",    "work_site_status": "active",    "position_id": "032d4063-2a79-45e6-b047-5b4876b59afc",    "position_name": "Barber",    "position_status": "active",    "member_id": "6664453a-c118-48f1-897e-3df62d45bd84",    "member_full_name": "John Doe",    "shift_swap_cutoff_time": null,    "type": "RosteredShift",    "work_type_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",    "work_type_name": "Full time",    "shift_swap": {      "id": "d71690b7-381f-4d54-8bdc-e4fd9d3e3be1",      "requesting_shift_id": "4a35ccb6-8ff6-4719-b7fb-726b40467957",      "receiving_shift_id": "dbab7b49-b40b-4e0d-ae69-a5fde016c5c7",      "status": "awaiting_receiver",      "requesting_notes": null    },    "breaks": [      {        "start_time": "2024-06-14T12:00:00.000Z",        "end_time": "2024-06-14T13:00:00.000Z"      }    ]  }}

Get Rostered Shifts Cost

Get the summarized rostered shift costs for a given period of time

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/cost

Path Parameters

organisation_iduuidrequired

ID of the organisation

Query Parameters

start_datestringrequired

Start datetime of the range.

end_datestringrequired

End datetime of the range. Must not be more than 30 days from the start date.

work_site_idsuuid[]

Work site IDs to filter by, applicable only for Payroll-integrated organisations

position_idsuuid[]

Position IDs to filter by, applicable only for Payroll-integrated organisations

location_idsuuid[]

Location IDs to filter by, applicable only for standalone HR organisations

member_idsuuid[]

Member IDs to filter by

statusesstring[]

Statuses to filter by

Response Body

The summarized rostered shift costs for a given period of time.

dataobject

costsobject[]

Costs of the rostered shifts

open_shiftsobject[]

Open (unassigned) shifts. Not included in cost calculation

Example

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

Response

{  "data": {    "costs": [      {        "total_cost": 1471.15,        "unit": "AUD",        "shift_ids": [          "1557a4b4-78b8-464f-bc7f-bf160d8285ed",          "68187eff-fc05-4731-a6fe-5866941c4fee"        ]      },      {        "total_cost": 761.54,        "unit": "GBP",        "shift_ids": [          "624cd1d5-9863-41a7-a7e0-b87074d85b11",          "4afb4820-6e5a-4f24-b1ec-1add7db1ec34"        ]      }    ],    "open_shifts": [      {        "shift_id": "ca2685b6-ed99-4df9-8736-1f5c493294a0",        "start_time": "2025-11-06T09:00:00.000Z",        "end_time": "2025-11-06T17:00:00.000Z"      },      {        "shift_id": "def126d9-b0d8-4c0b-9da6-91fa69a1e257",        "start_time": "2025-11-07T09:00:00.000Z",        "end_time": "2025-11-07T17:00:00.000Z"      }    ]  }}

Get Roles/Tags

Get roles (standalone HR) or tags (payroll-connected)

GET

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

Path Parameters

organisation_iduuidrequired

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

The roles available in this organisation

dataobject

itemsobject[]

iduuid

ID of the role

namestring

Name of the role

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

Response

{  "data": {    "items": [      {        "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "name": "Full time"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Bulk Create Rostered Shifts

Create a background job to handle rostered shifts bulk creation.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_create

Path Parameters

organisation_iduuidrequired

ID of the organisation

Request Body

start_date_timedatetimerequired

Start date time of the rostered shifts

end_date_timedatetimerequired

End date time of the rostered shifts

number_of_shiftsnumberrequired

Number of shifts to create, if this number is greater than the number of member_ids, the remaining shifts are created as open shifts

work_site_iduuid

ID of the work site to create rostered shifts for (position based rostering only)

position_iduuid

ID of the position to create rostered shifts for (position based rostering only)

location_iduuid

ID of the location to create rostered shifts for (cost centre based rostering only)

member_idsuuid[]

IDs of the members to create rostered shifts for

biddable_member_idsuuid[]

IDs of the biddable members for the open shifts (only applicable if member_ids is not provided)

breaksobject[]

Breaks to create for the rostered shifts

notesstring

Notes for the rostered shifts

publishedboolean

Whether to publish the rostered shifts immediately after creation

Response Body

The status of the rostered shift bulk job. Use the Get Rostered Shifts Bulk Job Status API to confirm successful shift creation.

dataobject

iduuid

ID of the rostered shift bulk job

statusenum<string>

Status of the rostered shift bulk job

job_errorsstring[]

Errors of the rostered shift bulk job

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_create" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "start_date_time": "2025-11-06T09:00:00.000Z",    "end_date_time": "2025-11-07T09:00:00.000Z",    "number_of_shifts": 10,    "member_ids": [      "6664453a-c118-48f1-897e-3df62d45bd84"    ],    "biddable_member_ids": [      "6664453a-c118-48f1-897e-3df62d45bd84"    ],    "breaks": [      {        "start_time": "2025-11-06T12:00:00.000Z",        "end_time": "2025-11-06T13:00:00.000Z"      }    ],    "notes": "Bulk created shifts",    "published": true  }'

Response

{  "data": {    "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",    "status": "completed",    "job_errors": []  }}

Bulk Publish Rostered Shifts

Publish up to 30 draft or unpublished rostered shifts in a single request. Processing is asynchronous.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_publish

Path Parameters

organisation_iduuidrequired

ID of the organisation

Request Body

idsuuid[]required

IDs of the rostered shifts to publish (1 to 30 IDs)

Response Body

Returns 202 Accepted. The shifts are processed asynchronously in a background job.

When the status is completed, the result contains published_count, and optionally awaiting_confirmation_count, blocked_count and blocked_rule_name.

dataobject

job_idstring

ID of the background job. Use it with the Get Rostered Shifts Bulk Job Status API to poll for the result.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_publish" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "6ddbfb24-8153-42a9-9248-c41c9b6c755e",      "7eebfc35-9264-53b0-a359-d52d0c7d866f"    ]  }'

Response

{  "data": {    "job_id": "bulk_publish_6ddbfb24-8153-42a9-9248-c41c9b6c755e"  }}

Bulk Unpublish Rostered Shifts

Unpublish up to 30 published (or awaiting confirmation) rostered shifts in a single request. Processing is asynchronous.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_unpublish

Path Parameters

organisation_iduuidrequired

ID of the organisation

Request Body

idsuuid[]required

IDs of the rostered shifts to unpublish (1 to 30 IDs)

Response Body

Returns 202 Accepted. The shifts are processed asynchronously in a background job.

If any shift cannot be unpublished (e.g. it is not currently published), the job status becomes failed with the reason in job_errors.

dataobject

job_idstring

ID of the background job. Use it with the Get Rostered Shifts Bulk Job Status API to poll for the result.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_unpublish" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "6ddbfb24-8153-42a9-9248-c41c9b6c755e",      "7eebfc35-9264-53b0-a359-d52d0c7d866f"    ]  }'

Response

{  "data": {    "job_id": "bulk_unpublish_6ddbfb24-8153-42a9-9248-c41c9b6c755e"  }}

Bulk Delete Rostered Shifts

Soft-delete up to 30 draft or unpublished rostered shifts in a single request. Processing is asynchronous.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_destroy

Path Parameters

organisation_iduuidrequired

ID of the organisation

Request Body

idsuuid[]required

IDs of the rostered shifts to delete (1 to 30 IDs)

Response Body

Returns 202 Accepted. The shifts are processed asynchronously in a background job.

When the status is completed, the shifts have been soft-deleted. If the deletion fails, the status becomes failed with the reason in job_errors.

dataobject

job_idstring

ID of the background job. Use it with the Get Rostered Shifts Bulk Job Status API to poll for the result.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/bulk_destroy" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "6ddbfb24-8153-42a9-9248-c41c9b6c755e",      "7eebfc35-9264-53b0-a359-d52d0c7d866f"    ]  }'

Response

{  "data": {    "job_id": "bulk_destroy_6ddbfb24-8153-42a9-9248-c41c9b6c755e"  }}

Get Rostered Shifts Bulk Job Status

Get the status of a rostered shift bulk job by its job id. The job can be a bulk create, bulk publish, bulk unpublish or bulk delete job, using the job_id returned by the corresponding endpoint.

For bulk publish jobs, the result may include extra fields such as published_count, awaiting_confirmation_count, blocked_count and blocked_rule_name.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/job_status/:job_id

Path Parameters

organisation_iduuidrequired

ID of the organisation

job_iduuidrequired

ID of the rostered shift bulk job

Response Body

The status of the rostered shift bulk job

dataobject

iduuid

ID of the rostered shift bulk job

statusenum<string>

Status of the rostered shift bulk job

job_errorsstring[]

Errors of the rostered shift bulk job

Example

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

Response

{  "data": {    "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",    "status": "completed",    "job_errors": []  }}