Sometimes employees may have consistent times where they are unavailable to work. They may be a student with university lectures or have other regular family commitments. To help with this, via the API you are able to set an employees unavailability to work.

When this is done, it defines the periods of the week that the employee is unavailable to work. This can be done as both a one off, or a regular time block, for example weekly. When set this will mean that the system ignores this employee when building out auto schedules.

Process for adding Employee Unavailability

curl --location --request POST 'https://{install}.{geo}.deputy.com/api/v1/supervise/unavail

Sample Payload - Simple Unavailability

{"blnSubmitSuperUnavail":true,
 "intAssignedEmployeeId":639,
 "start":{"timestamp":"1736168400"},
 "end":{"timestamp":"1736254800"},
 "strComment":"Comment"}

Data Element	Mandatory	Info
blnSubmitSuperUnavail	Yes	This indicates you are submitting unavailability for the employee
intAssignedEmployeeId	Yes	The record id of the employee you are submitting unavailability for
start	Yes	The start time of the unavailability in unix time
end	Yes	The end time of the unavailability in unix time
strComment	Yes	A comment to go along with the unavailability record that the manager will see. This can just be an empty string.

Sample Payload - Recurring Unavailability

{
 "blnSubmitSuperUnavail":true,
 "intAssignedEmployeeId":639,
 "start":{"timestamp":"1736168400"},
 "end":{"timestamp":"1736254800"},
 "strComment":"Weekly",
 "recurrence":{"FREQ":"WEEKLY","INTERVAL":1,"BYDAY":"MO"}
}

Data Element	Mandatory	Info
blnSubmitSuperUnavail	Yes	This indicates you are submitting unavailability for the employee
intAssignedEmployeeId	Yes	The record id of the employee you are submitting unavailability for
start	Yes	The start time of the unavailability in unix time
end	Yes	The end time of the unavailability in unix time
strComment	Yes	A comment to go along with the unavailability record that the manager will see. This can just be an empty string.
recurrence	Yes if recurring	Defines the recurrence interval
recurrence - FREQ	Yes if recurring	Defines the frequency of the unavailability. WEEKLY or MONTHLY. For those which might be fortnightly etc or every four weeks, the INTERVAL is used.
recurrence - INTERVAL	Yes if recurring	The interval for the unavailability. For example if FREQ is WEEKLY and INTERVAL is 1 it means every week. If INTERVAL is 2 it means fortnightly etc.
recurrence - BYDAY	Yes if recurring	The days of the week to set this unavailability. Can be more than one. Days are defined by the first two letters of the day so for example MO = Monday, WE = Wednesday etc. If you are defining a monthly unavailability for example the 6th of every month this field is called BYMONTHDAY and you define the day of the month. For example BYMONTHDAY: 6

Sample Response

{
    "Id": 242,
    "Employee": 639,
    "Type": 0,
    "MaxDateRecurringGenerated": null,
    "StartTime": 1736168400,
    "EndTime": 1736254800,
    "Date": "2025-01-07T00:00:00+11:00",
    "Comment": "Comment",
    "Schedule": 0,
    "Creator": 1,
    "Created": "2025-01-06T11:35:11+11:00",
    "Modified": "2025-01-06T11:35:11+11:00",
    "StartTimeLocalized": "2025-01-07T00:00:00+11:00",
    "EndTimeLocalized": "2025-01-08T00:00:00+11:00",
}

Data Element	Info
Id	The id of the new record which has been added
Employee	The id of the record for the Employee which has had the unavailability added
Type	The type of unavailabilty. 0 = one off, 1 = recurring
MaxDateRecurringGenerated	If it is a recurring record it will define here the maximum date that was generated for this record. Deputy does not add infinite records for future unavailability so it is important to track this date in a recurring situation.
StartTime	The start time in unix time of the unavailability
EndTime	The end time in unix time of the unavailability
Date	The first date of the unavailability in zulu format with timezone offset
Comment	The comment added against the unavailability
Schedule	If recurring the id record of the schedule which is driving the recurrence is included here
Creator	The id of the record of the Deputy user who created the record (even via API as API impersonates a user via bearer token etc)
Created	The created time of the record
StartTimeLocalized	The start time in zulu format with the timezone offset for the record
EndTimeLocalized	The end time in zulu format with the timezone offset for the record