Using the API to auto build Deputy shifts

The Deputy API allows you to automatically build or fill shifts within a Deputy schedule by simply providing a few parameters. These include the areas for which the shifts should be processed, the start time for the week of shifts (e.g. midnight on the first day of the business's working week), and the end time for the shift generation process. With this information, the API can handle the rest of the shift generation process for you.

Auto building shifts via the Deputy API

Once you have all the information required you can follow the below guide to start this process.

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v1/supervise/roster/autobuild'

Sample payload

{
  arrOpUnitIds: [431],
  intStartTimestamp: 1669813200,
  intEndTimestamp: 1670417999,
  freq: 0.25,
  base: 'RequiredStaff',
  lengths: [4,8],
}

Data Elements

Data Element	Info
arrOpUnitIds	This is an array which contains the id's of the areas that should be included in the shift auto build process.
intStartTimestamp	Epoch timestamp for when the period of shifts being generated should start.
IntEndTimestamp	Epoch timestamp for when the period of shifts being generated should end
freq	The structure of the shifts. By default this is 0.25 which represents 15 minutes. You can also have 0.50 which is half an hour and 1.0 which is an hour. This tells Deputy how to break these individual shifts up, for example, if you define a freq of 1.0 all shifts will be exact hours, whilst if you define 0.25 you may have a shift which lasts 4 hrs and 45 minutes.
base	The base is the metric you would like Deputy to use when generating these shifts. RequiredStaff - This metric tells Deputy to perform some calculations based on historical data and forecasting to determine what staff will be required for the period defined MinimumCoverage - This metric tells Deputy to build the shifts in such a way that it offers minimum coverage to the business for the period of time *Historical - This metric focuses on previous shift generations to determine what the business needs in the next period.
lengths	This array allows you to define the lengths of shifts you would like to see prioritised in the generation process. In the example [4,8] this means that by default you would like to have shifts of 4 hours and where this is not possible, Deputy is instructed to try and generate an 8 hour shift.

Response

The auto build/fill generation process is async and will not necessarily be completed when the first response is returned. In the response an auto build id will be returned for example autobuild638d443c8a995. This acts like a receipt for the process which has kicked off, and you can use it to check the progress of the autobuild at any time with the following URL.

curl --request GET --url 'https://{install}.{geo}.deputy.com/api/v1/supervise/roster/checkautobuild/{autobuildid}'

This will return a number between 1 and 100 in the response. This number defines how far into the process the autobuild is. A number of 100 represents that the process is complete and the user should see these new shifts within their Deputy install.