Roster Template

Get Roster Templates

Get a paginated list of roster templates for an organisation, optionally filtered by view mode.

GET

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

Path Parameters

organisation_iduuidrequired

ID of the organisation

Query Parameters

view_modeenum<string>

If set, only templates whose period length matches the view mode are returned

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

The roster templates the current user can access

dataobject

itemsobject[]

iduuid

ID of the roster template

namestring

Name of the roster template

descriptionstring

Description of the roster template

time_costnumber

Total rostered time of the template, in seconds

shift_countinteger

Number of shifts in the template

staff_countinteger

Number of distinct members rostered in the template

work_sitesstring[]

Names of the work sites referenced by the template shifts

positionsstring[]

Names of the positions referenced by the template shifts

locationsstring[]

Names of the locations referenced by the template shifts

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

Response

{  "data": {    "items": [      {        "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",        "name": "Standard week",        "description": "Default roster used for the main store",        "time_cost": 144000,        "shift_count": 12,        "staff_count": 5,        "work_sites": [          "LA Work Site"        ],        "positions": [          "Barber"        ],        "locations": [          "John Doe Hospital"        ]      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Create Roster Template

Create a roster template by taking a snapshot of the rostered shifts already scheduled within a date range.

Datetime values are the local date and time at the work location, not converted to UTC. Send them in ISO 8601 format, with or without a trailing Z (e.g. 2024-01-01T00:00:00 or 2024-01-01T00:00:00Z). The Z is optional and does not mean UTC here. Values with any other time zone offset (e.g. +08:00) are rejected with a 400.

POST

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

Path Parameters

organisation_iduuidrequired

ID of the organisation

Request Body

namestringrequired

Name of the roster template. Must be unique within the organisation

descriptionstring

Description of the roster template

start_date_timedatetimerequired

Start of the date range to take the shift snapshot from, in local time at the work location (not converted to UTC)

end_date_timedatetimerequired

End of the date range to take the shift snapshot from, in local time at the work location (not converted to UTC). Must not be before start_date_time, and the date range must not exceed one month and one day

Response Body

The created roster template

dataobject

iduuid

ID of the roster template

namestring

Name of the roster template

descriptionstring

Description of the roster template

time_costnumber

Total rostered time of the template, in seconds

shift_countinteger

Number of shifts in the template

staff_countinteger

Number of distinct members rostered in the template

work_sitesstring[]

Names of the work sites referenced by the template shifts

positionsstring[]

Names of the positions referenced by the template shifts

locationsstring[]

Names of the locations referenced by the template shifts

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/roster_templates" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Standard week",    "description": "Default roster used for the main store",    "start_date_time": "2024-01-01T00:00:00Z",    "end_date_time": "2024-01-08T00:00:00Z"  }'

Response

{  "data": {    "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e",    "name": "Standard week",    "description": "Default roster used for the main store",    "time_cost": 144000,    "shift_count": 12,    "staff_count": 5,    "work_sites": [      "LA Work Site"    ],    "positions": [      "Barber"    ],    "locations": [      "John Doe Hospital"    ]  }}

Delete Roster Template

Permanently delete a roster template and the shifts it contains. Rostered shifts that were previously created by applying the template are not affected.

DELETE

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

Path Parameters

organisation_iduuidrequired

ID of the organisation

iduuidrequired

ID of the roster template to delete

Response Body

Returns HTTP 204 No Content on success.

Example

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

Response

This endpoint does not return a response body.

Apply Roster Template

Create rostered shifts from a roster template, starting from the given date. The shifts are created asynchronously by a background job, so the endpoint returns HTTP 202 Accepted with a job_id straight away. Use the Get Roster Template Job Status API to check the outcome.

start_date must be a date in YYYY-MM-DD format.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/roster_templates/:id/apply

Path Parameters

organisation_iduuidrequired

ID of the organisation

iduuidrequired

ID of the roster template to apply

Request Body

start_datedaterequired

The date the template shifts are applied from, in YYYY-MM-DD format

Response Body

The apply job was accepted. Poll the job status using the returned job_id

dataobject

job_iduuid

ID of the apply job. Use it to poll the job status with the Get Roster Template Job Status API

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/roster_templates/:id/apply" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "start_date": "2024-02-01"  }'

Response

{  "data": {    "job_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"  }}

Get Roster Template Job Status

Get the status of a roster template apply job started by the Apply Roster Template API.

Once the job reaches a final state (success or failed), its result can only be retrieved once — subsequent requests for the same job_id return 404. A job_id that does not belong to the organisation also returns 404. Keep polling while the status is pending.

GET

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

Path Parameters

organisation_iduuidrequired

ID of the organisation

job_iduuidrequired

ID of the apply job, returned by the Apply Roster Template API

Response Body

The status of the roster template apply job

dataobject

statusenum<string>

Current status of the apply job. pending: the job is still processing. success: all shifts were created. failed: the job failed with an unrecoverable error. conflict: the job stopped because some shifts could not be created without conflict resolution

shifts_created_countinteger

Number of rostered shifts created. Returned when status is success or conflict; null otherwise

errorobject

Error details. Returned when status is failed

Example

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

Response

{  "data": {    "status": "success",    "shifts_created_count": 12,    "error": null  }}