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 ElementMandatoryInfo
EmployeeYesThe id record number of the employee who is requesting leave
LeaveRuleYesThe 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.
CompanyYesThe location which the leave application is being applied against for unavailability/timesheet purposes.
DateStartYesThe start date of the leave in YYYY-MM-DD format
StartYesThe start time of the leave in unix timestamp format
DateEndYesThe end date of the leave in YYYY-MM-DD format
EndYesThe end time of the leave in unix timestamp format
CommentYesA 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 ElementInfo
IdThe id record number of the leave request
EmployeeThe id record number of the employee the leave request is for
EmployeeHistoryThe id record number of the employee history which can be used with the resource EmployeeHistory API
CompanyThe id of the location that the timesheet/leave application is associated with
LeaveRuleThe id of the record number for the leave type that was requested.
StartThe start time of the leave in unix timestamp
DateStartThe date of the start of the leave including UTC offset
EndThe end time of leave in unix timestamp
DateEndThe date of the end of the leave including UTC offset
DaysThe total number of days of the leave, typically not used as tracked in hours.
ApproverTimeThis will be null in this scenario as the time is not approved and awaiting manager approval
ApproverPayThis will be null in this scenario as the pay is not approved and awaiting manager approval
CommentThis is the comment the employee included with the leave request
StatusThis 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.
ApprovalCommentAny comment the approving manager has left against the leave request. This will be null in this scenario
TotalHoursThe total number of hours for the request. This can be null
ExternalIdIf this has been sent to a third party integration from Deputy, that Deputy built, the record of the linking ID would appear here.
AllDayWhether 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.
CreatorThe id of the record of the Deputy employee that created the record
CreatedThe time the leave request was created with UTC offset
ModifiedThe time the leave request was last modified with UTC offset.
StartTimeLocalizedThe start time of the leave including UTC offset
EndTimeLocalizedThe end time of the leave including UTC offset
TimezoneThe timezone of the installation the leave request is from
DateStartAllDayWhether the start date was tagged as all day leave by the employee on request
DateEndAllDayWhether the end date was tagged as all day leave by the employee on request
NotifyManagerArray
LeavePayLineArrayIf 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.