Scheduled Shift

Get Scheduled Shifts

List all the scheduled 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 scheduled shifts to filter by

location_idsuuid[]

Location IDs of the scheduled shifts to filter by

member_idsuuid[]

Member IDs of the scheduled 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 scheduled shifts current user can access

dataobject

itemsobject[]

iduuid

ID of the scheduled shift

start_timedatetime

Shift start time

end_timedatetime

Shift end time

statusstring

Status of the scheduled shift

notesstring

Notes for the scheduled shift

is_open_shiftboolean

Whether the shift is open

location_iduuid

ID of the location where the shift is scheduled

location_namestring

Name of the location where the shift is scheduled

work_site_iduuid

ID of the work site where the shift is scheduled

work_site_namestring

Name of the work site where the shift is scheduled

work_site_statusenum<string>

The status of the work site where the shift is scheduled

position_iduuid

ID of the position for which the shift is scheduled

position_namestring

Name of the position for which the shift is scheduled

position_statusenum<string>

The status of the position for which the shift is scheduled

member_iduuid

ID of the member scheduled for the shift

member_full_namestring

Full name of the member scheduled 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 Scheduled Shift

Get scheduled 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 scheduled shift record

Response Body

The scheduled shift record

dataobject

iduuid

ID of the scheduled shift

start_timedatetime

Shift start time

end_timedatetime

Shift end time

statusstring

Status of the scheduled shift

notesstring

Notes for the scheduled shift

is_open_shiftboolean

Whether the shift is open

location_iduuid

ID of the location where the shift is scheduled

location_namestring

Name of the location where the shift is scheduled

work_site_iduuid

ID of the work site where the shift is scheduled

work_site_namestring

Name of the work site where the shift is scheduled

work_site_statusenum<string>

The status of the work site where the shift is scheduled

position_iduuid

ID of the position for which the shift is scheduled

position_namestring

Name of the position for which the shift is scheduled

position_statusenum<string>

The status of the position for which the shift is scheduled

member_iduuid

ID of the member scheduled for the shift

member_full_namestring

Full name of the member scheduled 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 Scheduled Shifts Cost

Get the summarized scheduled 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 scheduled shift costs for a given period of time.

dataobject

costsobject[]

Costs of the scheduled 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 Scheduled Shifts

Create a background job to handle scheduled 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 scheduled shifts

end_date_timedatetimerequired

End date time of the scheduled 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 scheduled shifts for (position based rostering only)

position_iduuid

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

location_iduuid

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

member_idsuuid[]

IDs of the members to create scheduled 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 scheduled shifts

notesstring

Notes for the scheduled shifts

publishedboolean

Whether to publish the scheduled shifts immediately after creation

Response Body

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

dataobject

iduuid

ID of the scheduled shift bulk job

statusenum<string>

Status of the scheduled shift bulk job

job_errorsstring[]

Errors of the scheduled 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 Scheduled Shifts

Publish up to 30 draft or unpublished scheduled 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 scheduled 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 Scheduled 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 Scheduled Shifts

Unpublish up to 30 published (or awaiting confirmation) scheduled 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 scheduled 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 Scheduled 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 Scheduled Shifts

Soft-delete up to 30 draft or unpublished scheduled 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 scheduled 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 Scheduled 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 Scheduled Shifts Bulk Job Status

Get the status of a scheduled 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 scheduled shift bulk job

Response Body

The status of the scheduled shift bulk job

dataobject

iduuid

ID of the scheduled shift bulk job

statusenum<string>

Status of the scheduled shift bulk job

job_errorsstring[]

Errors of the scheduled 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": []  }}