Push shifts into the roster

Create, check, publish and cancel shifts from another system.

This guide covers creating shifts from a scheduling tool, checking them, and publishing them to staff.

Token permissions: Roster Read-write. Clients Read and Staff Read help you look up ids.

How shifts are created

POST /shifts follows the same rules as the Imploy roster, including funding and budget checks, leave, duplicates, segments and billing. Shapes depend on the request:

One client is a normal shift. Two or more is a group shift.
No staff is a shift pool shift. Several staff is a multi-staff shift.
A shift is saved as a draft unless you send publish: true. Drafts aren't visible to staff.

The response returns the new refs, like a:123.

A safe flow

Look up valid services

Call GET /services (with client_id if you can). Shift service names must be from this list.

Find a free worker

Call GET /staff/available for the time you need.

Create drafts

Use POST /shifts, or POST /shifts/bulk for up to 50. Each shift in a bulk call is saved on its own, and the response lists successes and failures.

Check award warnings

Call GET /shifts/warnings with the new refs (up to 100). It returns only shifts with SCHADS warnings, such as short shifts, overtime, broken shifts and rest between shifts.

Publish

Call POST /shifts/publish. Staff are notified. Send unpublish: true to pull shifts back to draft.

POST /shifts/publish without refs affects every draft shift in the date range. Send refs unless you mean all of them.

Change a shift

PATCH /shifts/{ref} edits a shift. Send only what changes. For a recurring shift, set scope to this or this_and_following. Completed and cancelled shifts can't be edited.
POST /shifts/copy copies up to 50 shifts to another date, keeping relative days and times.
POST /shifts/{ref}/cancel needs reason, charge_client and pay_staff. The shift stays on the roster as cancelled.
DELETE /shifts takes up to 50 refs in the body.

Read shifts back

GET /shifts needs from and returns up to 31 days (7 by default). Filter by client_id, staff_id, site_id, or unassigned_only to find open shifts. GET /shifts/{ref} has the full detail.

Bringing in history

To load past or existing shifts, use POST /shifts/import instead. See Import data.

Roster reference

All shift endpoints.

Webhook events

appointment.created, updated, cancelled and deleted.

Was this page helpful?