Skip to content

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

shift_assignments.list: Parameters
FieldTypeDescription
employee_id (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_since (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)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

shift_assignments.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
org_unit_idstring (uuid)requirednullableUnit of the plan; null for a plan without a unit.
employee_idstring (uuid)required
shift_type_idstring (uuid)required
shift_codestringrequiredShort code of the shift type.
datestring (date)requiredThe day the shift starts.
start_timestringrequired
end_timestringrequiredEnd time (HH:MM); the next day when it is earlier than the start.
break_minutesintegerrequired
sourcestringrequiredmanual: from the plan screen; roster: from a published roster. Values: manual, roster
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

shift_assignments.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the assignment.

Responses

200 Successful

shift_assignments.get: Responses
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
org_unit_idstring (uuid)requirednullableUnit of the plan; null for a plan without a unit.
employee_idstring (uuid)required
shift_type_idstring (uuid)required
shift_codestringrequiredShort code of the shift type.
datestring (date)requiredThe day the shift starts.
start_timestringrequired
end_timestringrequiredEnd time (HH:MM); the next day when it is earlier than the start.
break_minutesintegerrequired
sourcestringrequiredmanual: from the plan screen; roster: from a published roster. Values: manual, roster
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout