Off Roster API

GET /api/integrations/external/off-roster/

Returns the employees who are off on a given date in the department associated with your API key: approved time off, planned time off such as holidays and extended leave, and shift trades where the employee gave their shift away.

See Basics for the base URL and authentication, and Error Handling for error responses.

Query parameters

Param	Required	Description
`date`	yes	The shift date in `YYYY-MM-DD` (e.g. `2026-05-07`).
`battalion`	conditional	A battalion id (from the Department API) or a 1-based index (`1`, `2`, …), used to filter the results. Required for departments with more than 3 battalions; optional otherwise. See Battalion selection.

Response — `200 OK`

A JSON array. Each item describes one off assignment:

Field	Type	Description
`employeeId`	string	The employee's payroll ID.
`employeeFullName`	string	Full name (`<first> <last>`).
`rank`	object \| null	The employee's rank as of the requested `date` (resolved from promotion history), or `null` if the employee has no rank on record.
`rank.code`	string	Short rank code (e.g. `FF`, `CAPT`).
`rank.name`	string	Human-readable rank name (e.g. `Firefighter`).
`assignmentType`	string	`TIME_OFF` for approved or planned time off (including holidays and extended leave), or `SHIFT_TRADE` when the employee traded their shift away.
`start`	string	ISO local-time start of the off period, format `YYYY-MM-DDTHH:MM` (department's local timezone, no zone suffix).
`end`	string	ISO local-time end of the off period, same format.
`payCodes`	array	The pay codes attached to the off assignment. Every assignment has at least one.
`payCodes[].code`	string	The pay code's code (e.g. `VAC`).
`payCodes[].name`	string	Human-readable name (e.g. `Vacation`).
`payCodes[].extCode`	string \| null	The external code configured for payroll exports, or `null` if not set.

Each item is one off assignment, not one employee. An employee with partial-day time off appears in both endpoints on the same date: their working segments in the Shift Schedule API and their off segment here. Planned time off is only reported on the days the employee is scheduled to work.

If there's no shift on the requested date (e.g. a future or past date with no schedule), the endpoint returns 200 OK with an empty array [].

Example

Request:

curl -i 'https://api.stationwise.com/api/integrations/external/off-roster/?date=2026-05-07&battalion=1' \
  -H 'X-API-Key: FE6vaHi4.qAAr87yrcjdO31a0WAYPbexilDcwt8ut'

Response (truncated):

[
  {
    "employeeId": "EMP-0042",
    "employeeFullName": "Alice Smith",
    "rank": {"code": "CPT", "name": "Captain"},
    "assignmentType": "TIME_OFF",
    "start": "2026-05-07T08:00",
    "end": "2026-05-07T20:00",
    "payCodes": [{"code": "VAC", "name": "Vacation", "extCode": "301"}]
  },
  {
    "employeeId": "EMP-0099",
    "employeeFullName": "Bob Jones",
    "rank": {"code": "FF", "name": "Firefighter"},
    "assignmentType": "SHIFT_TRADE",
    "start": "2026-05-07T08:00",
    "end": "2026-05-08T08:00",
    "payCodes": [{"code": "TRD", "name": "Shift Trade", "extCode": "410"}]
  }
]

Battalion selection

The battalion query parameter accepts the same values as the Shift Schedule API: a battalion id or a 1-based index.

Off employees have no unit on the requested date, so the filter follows the roster: the response lists the same employees the roster's Employees Off tab shows for that battalion. An employee is included when they have a planned or override position in the requested battalion, or when they have no planned position at all.

When battalion is omitted (allowed only for departments with ≤3 battalions), the response includes every battalion in the department.

Query parameters

Response — 200 OK

Example

Battalion selection

Response — `200 OK`