Shifts

GET /external/v1/shifts

Returns shift slots (templates) for a company. Optionally retrieves a single shift by ID.

Query Parameters

Parameter	Type	Required	Description
`shiftId`	string	No	If provided, returns a single shift instead of slot list
`branchId`	string	No	Filter slots by branch/location ID
`jobRoleId`	string	No	Filter slots by job role ID

Response: Slot List (default)

When called without shiftId, returns shift slot templates:

[
  {
    "id": "slot-uuid-1",
    "startTime": "09:00",
    "endTime": "17:00",
    "dayOfWeek": 1,
    "maxStaffRequired": 5,
    "timeZone": "Africa/Lagos",
    "hours": 8,
    "shiftName": "Morning Shift",
    "shiftColor": "#00AD57",
    "openShift": false,
    "isOncall": false,
    "unpaidBreak": 30,
    "swappable": true,
    "branch": {
      "id": "branch-uuid-1",
      "name": "Downtown Office"
    },
    "jobRole": {
      "id": "role-uuid-1",
      "title": "Cashier"
    }
  }
]

Slot Fields

Field	Type	Description
`id`	string	Slot template ID
`startTime`	string	Start time in `HH:mm` format
`endTime`	string	End time in `HH:mm` format
`dayOfWeek`	number	Day of week (0 = Sunday, 6 = Saturday)
`maxStaffRequired`	number	Maximum staff for this slot
`timeZone`	string	IANA time zone
`hours`	number	Slot duration in hours
`shiftName`	string	Display name for this shift
`shiftColor`	string	Hex color code
`openShift`	boolean	Whether this is an open shift
`isOncall`	boolean	Whether this is an on-call shift
`unpaidBreak`	number	Unpaid break time in minutes
`swappable`	boolean	Whether shift swaps are allowed
`branch`	object	Associated branch `{ id, name }`
`jobRole`	object	Associated job role `{ id, title }`

Response: Single Shift

When called with shiftId, returns a sanitized shift record:

{
  "id": "shift-uuid-1",
  "slotId": "slot-uuid-1",
  "branchId": "branch-uuid-1",
  "userId": "user-uuid-1",
  "status": "confirmed",
  "start": "2026-02-10T09:00:00.000Z",
  "end": "2026-02-10T17:00:00.000Z",
  "clockedIn": "2026-02-10T08:58:00.000Z",
  "clockedOut": "2026-02-10T17:02:00.000Z",
  "totalBreakTime": 30
}

See Schedules for field descriptions.

Examples

List all shift slots

curl -X GET "https://api.suprsync.com/external/v1/shifts" \
  -H "x-api-key: api_your_client_id" \
  -H "x-api-secret: sec_your_client_secret"

Get a single shift

curl -X GET "https://api.suprsync.com/external/v1/shifts?shiftId=shift-uuid-here" \
  -H "x-api-key: api_your_client_id" \
  -H "x-api-secret: sec_your_client_secret"

Filter by branch

curl -X GET "https://api.suprsync.com/external/v1/shifts?branchId=branch-uuid-here" \
  -H "x-api-key: api_your_client_id" \
  -H "x-api-secret: sec_your_client_secret"

Create Shift Slot

POST /external/v1/shifts/slots

Creates a new shift slot and the initial shift booking.

Request Body

Field	Type	Required	Description
`branchId`	string	Yes	Branch/location ID
`jobRoleId`	string	Yes	Job role ID
`startTime`	string	Yes	Start time `HH:mm`
`endTime`	string	Yes	End time `HH:mm`
`bookDate`	string	Yes	Date `YYYY-MM-DD`
`dayOfWeek`	number	Yes	Day of week (0-6)
`maxStaffRequired`	number	Yes	Max staff count
`timeZone`	string	Yes	IANA time zone
`shiftName`	string	Yes	Display name
`shiftColor`	string	Yes	Hex color
`openShift`	boolean	Yes	Whether open shift
`isOncall`	boolean	Yes	Whether on-call
`unpaidBreak`	number	Yes	Break time (minutes)
`hours`	number	No	Duration override
`writeUp`	string	No	Notes

curl -X POST "https://api.suprsync.com/external/v1/shifts/slots" \
  -H "x-api-key: api_your_client_id" \
  -H "x-api-secret: sec_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "branch-uuid-1",
    "jobRoleId": "role-uuid-1",
    "startTime": "09:00",
    "endTime": "17:00",
    "bookDate": "2026-02-15",
    "dayOfWeek": 0,
    "maxStaffRequired": 3,
    "timeZone": "America/New_York",
    "shiftName": "Morning Shift",
    "shiftColor": "#00AD57",
    "openShift": false,
    "isOncall": false,
    "unpaidBreak": 30
  }'

Response

{
  "slotId": "slot-uuid-new",
  "shift": {
    "id": "shift-uuid-new",
    "slotId": "slot-uuid-new",
    "branchId": "branch-uuid-1",
    "userId": "user-uuid-1",
    "status": "pending",
    "start": "2026-02-15T09:00:00.000Z",
    "end": "2026-02-15T17:00:00.000Z",
    "clockedIn": null,
    "clockedOut": null,
    "totalBreakTime": 30
  }
}

Book Shift

POST /external/v1/shifts/book

Books/assigns staff to an existing shift slot.

Request Body

Field	Type	Required	Description
`slotId`	string	Yes	Slot ID to book
`date`	string	Yes	Date `YYYY-MM-DD`
`assignees`	array	No	`[{ userId, userName }]`
`reminders`	array	No	`[{ minutesBefore }]`

curl -X POST "https://api.suprsync.com/external/v1/shifts/book" \
  -H "x-api-key: api_your_client_id" \
  -H "x-api-secret: sec_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "slotId": "slot-uuid-1",
    "date": "2026-02-15",
    "assignees": [{ "userId": "user-uuid-1", "userName": "john.doe" }],
    "reminders": [{ "minutesBefore": 30 }]
  }'

Response (200 OK)

Returns the booked shift details.

Error Response (400 Bad Request)

{
  "error": {
    "code": 400,
    "message": "Shift slot is not available on the selected day"
  }
}

Cancel Shift

DELETE /external/v1/shifts/:id

Cancels a specific shift booking.

curl -X DELETE "https://api.suprsync.com/external/v1/shifts/shift-uuid-1" \
  -H "x-api-key: api_your_client_id" \
  -H "x-api-secret: sec_your_client_secret"

Response

{
  "message": "Shift cancelled"
}