Shifts
Shifts endpoints: parameters, fields and example responses.
Developer documentation
Lists shift assignments
GET /api/v1/shift-assignments
Scope: shifts:read
Current assignments of published plans; draft plans and pending change requests are not returned. A deleted assignment does not show up with updated_since: the shift.assignment.changed event names the employee and the day, which is then read again with employee_id, from and to. The order is by ID and stable; no total count is returned. Sample records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
employee_ (query) | string (uuid) | Only assignments of this employee. |
from (query) | string (date) | Assignments not before this day (YYYY-MM-DD). |
to (query) | string (date) | Assignments not after this day (YYYY-MM-DD). |
updated_ (query) | string (date-time) | Only records whose updated_at is greater than or equal to this moment (ISO 8601 with a time zone). Inclusive: send the last updated_at you saw and deduplicate by ID. |
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
org_ | string (uuid)requirednullable | Unit of the plan; null for a plan without a unit. |
employee_ | string (uuid)required | |
shift_ | string (uuid)required | |
shift_ | stringrequired | Short code of the shift type. |
date | string (date)required | The day the shift starts. |
start_ | stringrequired | |
end_ | stringrequired | End time (HH:MM); the next day when it is earlier than the start. |
break_ | integerrequired | |
source | stringrequired | manual: from the plan screen; roster: from a published roster. Values: manual, roster |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"data": [
{
"id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"shift_type_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"shift_code": "G",
"date": "2026-07-06",
"start_time": "08:00",
"end_time": "16:00",
"break_minutes": 60,
"source": "manual",
"is_demo": false,
"created_at": "2026-06-25T14:00:00.000Z",
"updated_at": "2026-06-25T14:00:00.000Z"
}
],
"next_cursor": null
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Returns one shift assignment
GET /api/v1/shift-assignments/{id}
Scope: shifts:read
A record the key cannot see and a record that does not exist get the same 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the assignment. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
org_ | string (uuid)requirednullable | Unit of the plan; null for a plan without a unit. |
employee_ | string (uuid)required | |
shift_ | string (uuid)required | |
shift_ | stringrequired | Short code of the shift type. |
date | string (date)required | The day the shift starts. |
start_ | stringrequired | |
end_ | stringrequired | End time (HH:MM); the next day when it is earlier than the start. |
break_ | integerrequired | |
source | stringrequired | manual: from the plan screen; roster: from a published roster. Values: manual, roster |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"shift_type_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"shift_code": "G",
"date": "2026-07-06",
"start_time": "08:00",
"end_time": "16:00",
"break_minutes": 60,
"source": "manual",
"is_demo": false,
"created_at": "2026-06-25T14:00:00.000Z",
"updated_at": "2026-06-25T14:00:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout