Time Off

Time off endpoints allow management of time off/holidays in CMap

Get All TimeOff

HTTP GET v2/TimeOff/all

Returns all the time off

_Response

[{ 
	"id" : 234234,
	"actualDays" : 2, 
	"booked" : true, 
	"date" : "2015-07-01", 
	"duration" : 2, 
	"code" : "Holiday",
	"codeId" : 0,
	"notes" : "Some notes about the holiday", 
	"rejected" : true, 
	"requested" : true,
	"hours": 16,
	"isHoursBooking": false
}]

Get Current User’s TimeOff

HTTP GET v2/TimeOff

Returns all the time off for the logged in user

_Response

[
  { 
	"id" : 234234,
	"actualDays" : 2, 
	"booked" : true, 
	"date" : "2015-07-01", 
	"duration" : 2, 
	"code" : "Holiday",
	"codeId" : 0,
	"notes" : "Some notes about the holiday", 
	"rejected" : true, 
	"requested" : true,
	"Hours": 16,
	"IsHoursBooking": false
  },
  //...
]

Get TimeOff By Id

HTTP GET v2/TimeOff/5

Returns all the time off with the matching id

_Response

[
  { 
	"id" : 5,
	"actualDays" : 2, 
	"booked" : true, 
	"date" : "2015-07-01", 
	"duration" : 2, 
	"code" : "Holiday",
	"codeId" : 0,
	"notes" : "Some notes about the holiday", 
	"rejected" : true, 
	"requested" : true,
	"Hours": 16,
	"IsHoursBooking": false
  },
  //...
]

Get Allowance for Current User

HTTP GET v2/TimeOff/allowance

Returns the current years holiday allowance for the logged in user

_Response

{
	"days" : 25,
	"daysRemaining" : 4,
	"allowanceUnit": "Days",
	"carriedForward" : 3,
	"timeInLieu" = 0,
	"allowances" = [
		{"allowance":25, "allowanceRemaing" : 4, "code": "Holidays"},
		{"allowance":1, "allowanceRemaing" : 0, "code": "Birthday", "codeId" : 3},
		{"allowance":2, "allowanceRemaing" : 2, "code" : "Family Time", "codeId" : 2}
	]
}

Create TimeOff

HTTP POST v1/TimeOff

Request a new holiday. pm allows true or false, true indicating that this holiday will start at 12 noon. HolidayCodeId 0 indicates the standard Holiday Allowances, whereas specifying the HolidayCodeId as something other than 0 indicates a specific time off code. Returns Success if the holiday was successfully requested, or Conflict if any of the following is true:

There was already holiday request for this time period for this user
The user does not have sufficient allowance for part of the request (eg. if the holiday spans multiple years and an allowance hasn’t been set for the next year)
The end date falls after the user’s end date
The Hours property is being used and the duration of the booking exceeds the user’s working hours for that day

_Request

{
    "UserID": 123456, /* The user to book holiday for. Defaults to the user of the API, if you have the TimeOff admin permission then this can be a user other than the API user. */
    "Date": "2022-10-03",
    "Duration": 5,
    "Notes": "Optional notes about the holiday request",
    "pm": true | false,
    "status": "Requested" | "Approved", /* The status of the holiday, defaults to Requested, if you have the TimeOff admin permission then this can be created with the status Approved (No appproval emails will be sent). */
    "HolidayCodeID": 0 | [HolidayCodeId]
}

Duration can be replaced with Hours, to create the holiday length in hours (instead of the duration in days). Hours bookings are limited to a duration of up to 1 working day based on the user’s working hours for the specified date.

Update TimeOff

Update a requested holiday. pm allows true or false, true indicating that this holiday will start at 12 noon. HolidayCodeId 0 indicates the standard Holiday Allowances, whereas specifying the HolidayCodeId as something other than 0 indicates a specific time off code. Note that HolidayID must be specified.

Returns Success if the holiday was successfully updated, or Conflict if any of the following is true:

The holiday now clashes with another holiday request
The user does not have sufficient allowance for part of the request (eg. if the holiday spans multiple years and an allowance hasn’t been set for the next year)
The end date falls after the user’s end date
The Hours property is being used and the duration of the booking exceeds the user’s working hours for that day

_Request

{
    "HolidayId": 123456,
    "UserID": 123456, /* The user to assign the holiday to. Defaults to the user of the API, if you have the TimeOff admin permission then this can be a user other than the API user. */
    "Date": "2022-10-03",
    "Duration": 5,
    "Notes": "Optional notes about the holiday request",
    "pm": true | false,
    "status": "Requested" | "Approved", /* The status of the holiday, defaults to Requested, if you have the TimeOff admin permission then this can be updated to the status Approved (No appproval emails will be sent). */
    "HolidayCodeID": 0 | [HolidayCodeId]
}

Duration can be replaced with Hours, to save the holiday length in hours (instead of the duration in days). Hours bookings are limited to a duration of up to 1 working day based on the user’s working hours for the specified date.

If UserID is not specified it will default to the current user of the API. This will change to booking to be against that API user.

Delete TimeOff

HTTP DELETE v1/TimeOff/5

Deletes a TimeOff record

Create Time Off Allowance

Creates a holiday allowance for a user

{
	"UserID":"12345" /* who the entitlement is for */
	"Year":"2020" /* When the entitlement is for */
	"HolidayCodeID":"0" /* This has to be 0 for regular CMAP holidays or the ID of the client specific holiday code */
	"Days":"25" /* number of days for the entitlement */
	"CarriedForward":"0" /* number of days, only relevant for CMAP Holidays */
	"InLieu":"0" /* number of days, only relevant for CMAP Holidays */
}

"Days" field may be replaced by "Hours" and the entitlement will be saved as that number of hours.

* PUT v1/TimeOffAllowance Updates a holiday allowance for a user

{
	"UserID":"12345" /* who the entitlement is for */
	"Year":"2020" /* When the entitlement is for */
	"HolidayCodeID":"0" /* This has to be 0 for regular CMAP holidays or the ID of the client specific holiday code */
	"Days":"25" /* number of days for the entitlement */
	"CarriedForward":"0" /* number of days, only relevant for CMAP Holidays */
	"InLieu":"0" /* number of days, only relevant for CMAP Holidays */
}

"Days" field may be replaced by "Hours" and the entitlement will be saved as that number of hours.