Updating Regular Working Hours

Employees in Deputy can have regular working hours added to their profile. This can be related to employment law (where for example an employee under a particular age may have restricted hours) or personal desires such as a university student who can only work on particular days due to study requirements.

Regular Working Hours is available via the API, follow the below guide to use these features.

URL
The URL to interact with the regular working hours feature of Deputy is:

curl --POST 'https://{install}.{geo}.deputy.com/api/management/v2/agreed_hour/{employeeid}'

Sample Payload - Full Agreed Hours

The below payload covers a scenario where an employee has very specifically defined breaks and days of work.

{
    "agreedHour": {
        "threshold": 23.5,
        "applyThreshold": false,
        "workPeriod": {
            "cycle": "WEEKLY",
            "dayOfWeek": "TUESDAY",
            "startDate": "2022-08-02T00:00:00Z",
            "startCycleDate": "2023-02-07T00:00:00Z",
            "endCycleDate": "2023-02-13T23:59:59Z"
        },
        "details": {
            "weeks": [
                {
                    "week": "ONE",
                    "days": [
                        {
                            "day": 2,
                            "shifts": [
                                {
                                    "startTime": "09:00",
                                    "endTime": "18:00",
                                    "breaks": [
                                        {
                                            "breakType": "MEAL",
                                            "breakDuration": "00:30",
                                            "startBreakTime": "15:30",
                                            "endBreakTime": "16:00"
                                        }
                                    ],
                                    "location": 1,
                                    "area": 2,
                                    "totalHours": 8.5
                                }
                            ]
                        },
                        {
                            "day": 4,
                            "shifts": [
                                {
                                    "startTime": "09:00",
                                    "endTime": "17:00",
                                    "breaks": [
                                        {
                                            "breakType": "REST",
                                            "breakDuration": "00:30",
                                            "startBreakTime": "12:00",
                                            "endBreakTime": "12:30"
                                        }
                                    ],
                                    "location": 1,
                                    "area": 1,
                                    "totalHours": 8
                                }
                            ]
                        },
                        {
                            "day": 5,
                            "shifts": [
                                {
                                    "startTime": "09:00",
                                    "endTime": "17:00",
                                    "breaks": [
                                        {
                                            "breakType": "NO_BREAK",
                                            "breakDuration": "",
                                            "startBreakTime": "",
                                            "endBreakTime": ""
                                        }
                                    ],
                                    "location": 1,
                                    "area": 1,
                                    "totalHours": 8
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "workingDaysPerCycle": 3
    }
}

Element	Data Type	Info
threshold	Decimal	This is the total calculated hours for the period being defined. It is possible to set this as an upper limit for an employees hours using the applyThreshold element.
applyThreshold	Boolean true/false	This defines whether the threshold should be enforced. For example if this is set to true and you try to schedule the employee more than the threshold hours in the period, Deputy will block you from doing so. If this is set to false, this does not block this scenario.
workPeriod	Object	The work period object has elements which define the work period for which the regular working hours is set. For example it defines the first day of the week that should be taken into account in these calculations.
workPeriod - cycle	String	This defines the cycle of the work period. This can be WEEKLY, TWO_WEEK or FOUR_WEEK.
workPeriod - dayOfWeek	String	Defines the starting day of the week for the cycle. This can be MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
workPeriod - startDate	String	The start date and time in zulu time as to when this agreed hour profile should start.
workPeriod - startCycleDate	String	The time the cycle will first begin in zulu time.
workPeriod - endCycleDate	String	The time the cycle will first end in zulu time.
details	Object	When regular working hours contains specific information about days and hours, the details object will contain this information.
details - weeks	Array	This array contains information about the weeks which are included in the cycle, for each week there will be an object entry.
details - week	String	Which week of the cycle this array entry is referring to.
details - days	Array	Array of entries for individual days within the week.
days - day	Integer	Represents the day of the week 0 - Sunday 1 - Monday 2 - Tuesday 3 - Wednesday 4 - Thursday 5 - Friday 6 - Saturday
days - shifts	Array	Includes all the shift information for the day.
shifts - startTime	String	The start time of the shift in 24 hour time
shifts - endTime	String	The end time of the shift in 24 hour time
breaks	Array	Contains information for any breaks due in the shift.
breaks - breakType	String	The type of break. Can be MEAL, NO_BREAK or REST
breaks breakDuration	String	The duration of the break in minutes and hours
breaks - startBreaktime	String	The start time of the break if it has been specifically set
breaks - endBreakTime	String	The end time of the break if it has been specifically set
location	Integer	The id which represents the Deputy location where the shift takes place
area	Integer	The id which represents the area within the Deputy location where the shift takes place
totalHours	Integer	The total hours of all the days and shifts combined

Sample Payload - Simple Regular Working Hours

The below payload covers where you just want to set an agreed hours number as opposed to specific days and shifts.

{
  "agreedHour": {
    "threshold": 25,
    "applyThreshold": true,
    "workPeriod": {
      "cycle": "WEEKLY",
      "dayOfWeek": "TUESDAY",
      "startDate": "2022-05-10T00:00:00Z",
      "startCycleDate": "2022-05-02T00:00:00Z",
      "endCycleDate": "2022-05-08T23:59:59Z"
    },
    "workingDaysPerCycle": 3,
    "details": {
      "weeks": []
    }
  }
}

Element	Data Type	Info
threshold	Integer	The total number of hours for the regular working hours profile.
applyThreshold	Boolean true/false	Determines whether the threshold is a hard limit and Deputy will block additional scheduling or is a soft limit.
workPeriod	Object	This object contains information about the regular working hours cycle.
workPeriod - cycle	String	The cycle of the regular working hours profile. Can be WEEKLY, TWO_WEEKLY or FOUR_WEEKLY.
dayOfWeek	String	The day of the week the cycle starts. Can be MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
startDate	String	The start date of the regular working hours profile in zulu time.
startCycleDate	String	The first date of the regular working hours profile cycle in zulu time.
endCycleDate	String	The end date of the regular working hours profile cycle in zulu time.

Retrieving Regular Working Hours

You can retrieve the regular working hours profile for an employee by using this url.

URL

curl --GET 'https://{install}.{geo}.deputy.com/api/management/v2/agreed_hour/{employeeid}'