Shift swaps

Staff offering a shift to a named colleague, who accepts or declines in Shiftly. A cancelled offer is removed, not kept.

Needs the roster:read permission, depending on the operation. The business sees it as "Rosters and shifts".

Fields

ShiftSwap fields
Field	Type	Access	Meaning
id	string	Read-only	The swap.
shift_id	string	Read-only	The shift being handed over.
location_id	string	Read-only	Where the shift is.
from_employee_id	string	Read-only	Who offered the shift.
to_employee_id	string	Read-only	Who was asked to work it.
status	"pending", "accepted", "rejected"	Read-only	The colleague's answer. Who works the shift is the shift's own employee_id, not this status.
requested_at	timestamp	Read-only	When the shift was offered.
created_at	timestamp	Read-only	When the record was created.
updated_at	timestamp	Read-only	When the record last changed.

Operations

List shift swaps

GET/v1/shift-swaps

Permission: roster:read

Query parameters
Parameter	Type		Meaning
limit	integer, default 50, up to 200	Optional	How many records per page. Up to 200.
after	string	Optional	The next_cursor from the previous page.
updated_since	timestamp	Optional	Only records changed at or after this moment. Pair it with include_archived to see removals.
include_archived	"true", "false"	Optional	Include records that have been archived.
location_id	string	Optional	Only this location.
status	"pending", "accepted", "rejected"	Optional	Only records in this status.
shift_id	string	Optional
employee_id	string	Optional	Only this person.

200 response

{
  "data": [
    {
      "id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "shift_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "location_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "from_employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "to_employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "status": "pending",
      "requested_at": "2026-10-06T09:00:00+11:00",
      "created_at": "2026-10-06T09:00:00+11:00",
      "updated_at": "2026-10-06T09:00:00+11:00"
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Refusals
Status	When
400	The error's code is invalid_request or range_too_long. The Errors page describes each code.
401	The error's code is invalid_token or token_expired. The Errors page describes each code.
403	The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code.
404	There is nothing at this address, or no such record in this business.
429	Too many requests. Retry-After says when to try again.
500	Something went wrong at Shiftly. Quote the request id.
503	This environment is not set up for partner apps yet.

Get one shift swap

GET/v1/shift-swaps/{id}

Permission: roster:read

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "shift_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "location_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "from_employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "to_employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "status": "pending",
  "requested_at": "2026-10-06T09:00:00+11:00",
  "created_at": "2026-10-06T09:00:00+11:00",
  "updated_at": "2026-10-06T09:00:00+11:00"
}

Refusals
Status	When
400	The error's code is invalid_request or range_too_long. The Errors page describes each code.
401	The error's code is invalid_token or token_expired. The Errors page describes each code.
403	The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code.
404	There is nothing at this address, or no such record in this business.
429	Too many requests. Retry-After says when to try again.
500	Something went wrong at Shiftly. Quote the request id.
503	This environment is not set up for partner apps yet.