In this article, you can read about retrieving staffing calendar shifts, creating new shifts, and booking shifts to a job via the API.
Get Shifts in the Staffing Calendar
GET
Retrieves information about the Staffing Calendar shifts for a project.
https://api.recman.io/v2/get/index.php?scope=staffingCalendar&key={{api_key}}&page=1&projectId=856623&fromDate=2018-10-01&toDate=
2026-10-01&booked=0&minStaffingCalendarId=9241963| Field | Type | Required | Description |
|---|---|---|---|
| scope | string | Required | Must be set to staffingCalendar |
| key | string | Required | Your API key |
| page | integer | Required | Page number |
| projectId | integer | Required | ID of the related project |
| fromDate | date | Optional | Search parameter. Start of date range, format "YYYY-MM-DD" |
| toDate | date | Optional | Search parameter. End of date range, format "YYYY-MM-DD" |
| booked | integer | Optional | Search parameter. 0 = only unbooked shifts, 1 = only booked (confirmed) shifts |
| minStaffingCalendarId | integer | Optional | Search parameter. Only returns results with ID equal to or greater than the given value |
| candidateId | integer | Optional | Search parameter. Retrieves shifts connected to a specific candidate ID |
| candidateIds | string | Optional | Search parameter. Retrieves shifts connected to multiple candidate IDs, comma-separated (e.g. "5788046,5788047") |
Note
Different search parameters can be combined to narrow down the fetch request more precisely.
Each returned shift includes the following fields:
| Field | Type | Description |
|---|---|---|
| staffingCalendarId | integer | The ID of the shift |
| projectId | integer | The ID of the related project |
| name | string | Name of the shift |
| startDt | date-time | Start date and time of the shift, format "Y-m-d H:i:s" |
| endDt | date-time | End date and time of the shift, format "Y-m-d H:i:s" |
| breakTime | string | Break time, format "H:i:s" |
| booked | integer | Whether the shift is booked (0 or 1) |
| jobId | integer | The ID of the job the shift is booked to, if any |
| createUserId | integer | The ID of the user who created the shift |
| updateUserId | integer | The ID of the user who last updated the shift |
| created | date-time | Creation date, format "Y-m-d H:i:s" |
| updated | date-time | Last updated date, format "Y-m-d H:i:s" |
| invoiceNote | string | Note which ends up on the invoice |
| employeeNote | string | Note visible to the employee |
| internalNote | string | Note visible internally in the system |
| hasCandidateOffer | integer | Whether a candidate offer exists for the shift (0 or 1) |
| hasCompanyOffer | integer | Whether a company offer exists for the shift (0 or 1) |
Create Shift in the Staffing Calendar
POST
Creates a new shift in the staffing calendar. The operation must be set to insert and the scope tostaffingCalendar.
https://api.recman.io/v2/post/| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Name of the shift |
| projectId | integer | Required | ID of the related project |
| startDt | date-time | Required | Start date and time of the shift, format "yyyy-mm-dd hh:mm:ss" |
| endDt | date-time | Required | End date and time of the shift, format "yyyy-mm-dd hh:mm:ss" |
| breakTime | string | Optional | Break time, format "hh:mm:ss" |
| invoiceNote | string | Optional | Note which ends up on the invoice |
| employeeNote | string | Optional | Note which becomes visible to the employee |
| internalNote | string | Optional | Note visible internally in the system |
Note
To create a "whole day shift", set startDt and endDt like this: "startDt": "2026-01-20 00:00:00", "endDt": "2026-01-20 24:00:00"
(or alternatively "endDt": "2026-01-21 00:00:00").
Book Shift in the Staffing Calendar
POST
Books a shift to a job. The operation must be set to insert and the scope to bookStaffingCalendar.
https://api.recman.io/v2/post/| Field | Type | Required | Description |
|---|---|---|---|
| staffingCalendarId | integer | Required | ID of the shift to book |
| jobId | integer | Required | ID of the job being booked |
| projectId | integer | Required | ID of the related project |
| validate | boolean | Optional | "0" or "1". Default is 1 if not defined. If set to 0, it ignores the AML check (validation of working hours / working too much warning) |