> ## Documentation Index
> Fetch the complete documentation index at: https://integrations.stationwise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shift Schedule API

`GET /api/integrations/external/shift-schedule/`

Returns the position assignments for a given date in the department associated with your API key.

> See [Basics](../api-basics.md) for the base URL and authentication, and [Error Handling](../api-error-handling.md) 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](department-api.md)) 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](#battalion-selection). |

## Response — `200 OK`

A JSON array. Each item describes one position assignment:

| Field              | Type           | Description                                                                                                                        |
| ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `employeeId`       | string         | The employee's payroll ID.                                                                                                         |
| `employeeFullName` | string         | Full name (`<first> <last>`).                                                                                                      |
| `shiftStart`       | string         | ISO local-time start, format `YYYY-MM-DDTHH:MM` (department's local timezone, no zone suffix).                                     |
| `shiftEnd`         | string         | ISO local-time end, same format.                                                                                                   |
| `unit`             | string         | The unit name (e.g. `Engine 1`), or `Floater` when the employee is assigned without a unit.                                        |
| `stationName`      | string         | Station name, or empty string for floaters.                                                                                        |
| `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`).                                                                                     |

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:

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

Response (truncated):

```json
[
  {
    "employeeId": "EMP-0042",
    "employeeFullName": "Alice Smith",
    "shiftStart": "2026-05-07T08:00",
    "shiftEnd": "2026-05-08T08:00",
    "unit": "Engine 1",
    "stationName": "Station 1",
    "rank": {"code": "CPT", "name": "Captain"}
  },
  {
    "employeeId": "EMP-0099",
    "employeeFullName": "Bob Jones",
    "shiftStart": "2026-05-07T08:00",
    "shiftEnd": "2026-05-08T08:00",
    "unit": "Floater",
    "stationName": "",
    "rank": {"code": "FF", "name": "Firefighter"}
  }
]
```

***

## Battalion selection

The `battalion` query parameter accepts **either** a battalion **id** or a 1-based **index**:

* If the value matches the `id` of one of your department's battalions (see the [Department API](department-api.md)), it is resolved by id. This is the recommended, unambiguous form.
* Otherwise, it is treated as a **1-based index** into the department's battalions ordered by their internal sort order.

The two forms never collide: battalion ids are always ≥ 100, while indices are small. If the value is neither a known id nor a valid index, the request returns `400 Bad Request`.

**Filter semantics when `battalion` is set:**

* Assignments where the unit's station belongs to the requested battalion → **included**.
* Assignments on units in other battalions → **excluded**.
* **Floaters** (assignments without a unit) → **always included**, regardless of the requested battalion.

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