Sign in

v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB
Scheduling
Public API

Create Shift

Creates a new shift in the specified schedule.

OAuth Scopes: scheduling:shifts.write, time_tracking.write

post/api/v1/scheduling/shifts

Request body

scheduleIdstring uuid required

The ID of the schedule the shift belongs to.

namestring nullable

The name of the shift.

status'planned' | 'published' required

The status of the shift.

colorstring required

6 character color hex code.

timezonestring required

The timezone for the shift. Defaults to schedule timezone.

capacityinteger nullable

The expected headcount for the shift. If null, has no restrictions.

employeeIdsinteger[]

What employees are assigned to this shift?

startstring date-time required

UTC timestamp of the start of the shift.

endstring date-time required

UTC timestamp of the end of the shift.

recurrenceRulestring nullable

The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.

recurrenceDtstartstring nullable

The UTC start time for a recurring shift (anchor point for the recurrence rule).

recurrenceDtendstring nullable

The UTC end time for a recurring shift.

recurrenceUntilstring nullable

The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE).

Example request

{
  "scheduleId": "0199de9b-6bcb-77e7-941d-3caf74b9a372",
  "name": "Morning Shift",
  "color": "00FFAA",
  "timezone": "America/Denver",
  "capacity": 1,
  "start": "2025-01-01T06:00:00Z",
  "end": "2025-01-01T14:00:00Z",
  "recurrenceRule": "FREQ=WEEKLY;INTERVAL=1",
  "recurrenceDtstart": "2024-01-01T09:00:00Z",
  "recurrenceDtend": "2024-12-01T17:00:00Z",
  "recurrenceUntil": "2024-12-31T23:59:59Z"
}

Response

Successfully created a shift.

idstring required

The ID of the shift. This can be the UUIDv7 of the shift instance, or a composite ID (<recurringShiftDefinitionId>_<recurrenceId>) for uninstantiated recurring shifts.

scheduleIdstring uuid required

The ID of the schedule the shift belongs to.

namestring nullable

The name of the shift.

status'planned' | 'published' | 'cancelled' | 'deleted' required

The status of the shift.

colorstring required

6 character color hex code.

capacityinteger nullable

The expected headcount for the shift. Defaults to 1 if unset.

startstring date-time nullable required

UTC timestamp of the start of the shift.

endstring date-time nullable required

UTC timestamp of the end of the shift.

timezonestring required

The timezone for the shift.

recurrenceRulestring nullable

The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.

recurrenceIdstring nullable

The stable identifier for a recurrence, which is the original start of shift according to recurrence rules. Null for non-recurring shifts.

recurrenceDtstartstring nullable

The UTC start time for a recurring shift and the anchor point for the recurrence rule. Null for non-recurring shifts.

recurrenceDtendstring nullable

The UTC end time for a recurring shift. Null for non-recurring shifts.

recurrenceUntilstring nullable

The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE). Null for non-recurring shifts.

employeeIdsinteger[]

The list of employee IDs currently assigned.

unpublishedChangesobject nullable

The pending changes that have not been published.

createdAtstring date-time

UTC timestamp when the shift was created

updatedAtstring date-time nullable

UTC timestamp when the shift was last updated

deletedAtstring date-time nullable

UTC timestamp when the shift was deleted

Example response

{
  "id": "019aa09f-0712-74cb-9186-8ad0eb6038dc_20240101T093000",
  "scheduleId": "0199de9b-6bcb-77e7-941d-3caf74b9a372",
  "name": "Morning Shift",
  "color": "00FFAA",
  "capacity": 1,
  "start": "2025-01-01T06:00:00Z",
  "end": "2025-01-01T14:00:00Z",
  "timezone": "America/Denver",
  "recurrenceRule": "FREQ=WEEKLY;INTERVAL=1",
  "recurrenceId": "20240101T090000",
  "recurrenceDtstart": "2024-01-01T09:00:00Z",
  "recurrenceDtend": "2024-12-31T23:59:59Z",
  "recurrenceUntil": "2024-12-31T23:59:59Z",
  "employeeIds": [
    10,
    20
  ],
  "createdAt": "2025-01-01T06:00:00Z",
  "updatedAt": "2025-01-01T06:00:00Z",
  "deletedAt": "2025-01-01T06:00:00Z"
}