Adding a leave request for an employee
How to add a leave request for management approval in Deputy
Deputy uses hours based leave tracking
Due to the fact Deputy tracks leave in hours not days, the corresponding integration must do the same. This is due to the fact that to set the timesheet and unavailability correct for the employees during a time period, it is required to include the start time and end time of the leave. It may be that the employee is on leave for what is considered a 'full day' however Deputy for leave tracking and timesheets, still needs to know what that full day represents in hours. For some employees that might be 8 hours, for others it might be less or more depending on their average working schedules.
Process for adding draft leave timesheets
Deputy ha a full leave management process built into it where employees can add draft leave timesheets and managers approve them. In the scenario where you are only wanting to add draft
URL and Payload
curl --location --request POST 'https://{install}.{geo}.deputy.com/api/v1/resource/Leave
Sample Payload (Requires Manager Approval for the Leave Application
{
Employee: 4,
LeaveRule: 1,
Company: 1,
DateStart: "2022-01-14",
Start: 1642129200,
DateEnd: "2022-01-15",
End: 1642239900,
Comment: "Annual Leave"
}
| Data Element | Mandatory | Info |
|---|---|---|
| Employee | Yes | The id record number of the employee who is requesting leave |
| LeaveRule | Yes | The id record number of the Leave Rule being included (for example Annual Leave). You can obtain the list of Leave Rules present in the installation via the resource Leave Rules API. |
| Company | Yes | The location which the leave application is being applied against for unavailability/timesheet purposes. |
| DateStart | Yes | The start date of the leave in YYYY-MM-DD format |
| Start | Yes | The start time of the leave in unix timestamp format |
| DateEnd | Yes | The end date of the leave in YYYY-MM-DD format |
| End | Yes | The end time of the leave in unix timestamp format |
| Comment | Yes | A comment explaining the leave to the manager from the employee |
Sample Response
{
"Id": 2,
"Employee": 4,
"EmployeeHistory": 12176,
"Company": 1,
"LeaveRule": 1,
"Start": 1642129200,
"DateStart": "2022-01-14T00:00:00+11:00",
"End": 1642239900,
"DateEnd": "2022-01-15T23:59:59+11:00",
"Days": null,
"ApproverTime": null,
"ApproverPay": null,
"Comment": "Annual Leave",
"Status": 0,
"ApprovalComment": null,
"TotalHours": null,
"ExternalId": null,
"AllDay": false,
"Creator": 1,
"Created": "2024-09-23T10:32:28+10:00",
"Modified": "2024-09-23T10:32:28+10:00",
"StartTimeLocalized": "2022-01-14T14:00:00+11:00",
"EndTimeLocalized": "2022-01-15T20:45:00+11:00",
"TimeZone": "Australia/Sydney",
"DateStartAllDay": false,
"DateEndAllDay": false,
"NotifyManagerArray": [],
"LeavePayLineArray": [],
"_DPMetaData": {
"System": "Leave",
"CreatorInfo": {
"Id": 1,
"DisplayName": "Simon Hutchinson",
"EmployeeProfile": 1,
"Employee": 1,
"Photo": "https://862e8927033251.au.deputy.com/assets/php/image_preview.php/1/135/135",
"Pronouns": 0,
"CustomPronouns": null
},
"ApproverInfo": null
}
}
Data Elements
| Data Element | Info |
|---|---|
| Id | The id record number of the leave request |
| Employee | The id record number of the employee the leave request is for |
| EmployeeHistory | The id record number of the employee history which can be used with the resource EmployeeHistory API |
| Company | The id of the location that the timesheet/leave application is associated with |
| LeaveRule | The id of the record number for the leave type that was requested. |
| Start | The start time of the leave in unix timestamp |
| DateStart | The date of the start of the leave including UTC offset |
| End | The end time of leave in unix timestamp |
| DateEnd | The date of the end of the leave including UTC offset |
| Days | The total number of days of the leave, typically not used as tracked in hours. |
| ApproverTime | This will be null in this scenario as the time is not approved and awaiting manager approval |
| ApproverPay | This will be null in this scenario as the pay is not approved and awaiting manager approval |
| Comment | This is the comment the employee included with the leave request |
| Status | This is the status of the leave request. 0 is awaiting manager approval. 1 is approved. 2 is declined. 3 is employee cancelled. 4 is date approved without pay approved. 5. is pay approved without date approved. |
| ApprovalComment | Any comment the approving manager has left against the leave request. This will be null in this scenario |
| TotalHours | The total number of hours for the request. This can be null |
| ExternalId | If this has been sent to a third party integration from Deputy, that Deputy built, the record of the linking ID would appear here. |
| AllDay | Whether this leave request has been tagged as all day. This would be done by the employee in the Deputy UI if the leave request was added there, not via API. |
| Creator | The id of the record of the Deputy employee that created the record |
| Created | The time the leave request was created with UTC offset |
| Modified | The time the leave request was last modified with UTC offset. |
| StartTimeLocalized | The start time of the leave including UTC offset |
| EndTimeLocalized | The end time of the leave including UTC offset |
| Timezone | The timezone of the installation the leave request is from |
| DateStartAllDay | Whether the start date was tagged as all day leave by the employee on request |
| DateEndAllDay | Whether the end date was tagged as all day leave by the employee on request |
| NotifyManagerArray | |
| LeavePayLineArray | If the leave request has become an approved timesheet, the details of the pay related to it will appear in this array. |
Approved Leave Requests
The above scenario and payload should be used when you are requiring a managerial approval for the leave in Deputy before it begins to affect timesheets and leave balances. If your application is considered the source of truth for leave then it is likely you will be sending over approved leave requests to Deputy and should follow the below guide instead.
Sample Payload - Approved Leave Application
{
"Employee": 4,
"LeaveRule": 1,
"Company": 1,
"DateStart": "2024-01-18",
"DateEnd": "2024-01-19",
"Comment": "Annual Leave",
"Status": 1,
"ApprovalComment": "manager has approved"
}
By including the Status of 1 you are indicating to the Deputy system that this leave is already approved when being sent into the system.
The response that you get will be the same with the exception that the timesheet will be considered already manager approved.
Updated 23 days ago