Adding Hour Budgets to Deputy

You can add the following types of hour budgets to Deputy:

Weekly - The budget is set for the week and the user has to distribute amongst the days in the Deputy UI

Daily - Using the specific timestamp in the API call you can set the daily budgets using the API. We suggest the midnight timestamp for the day when using this option.


Daily vs Weekly

Users of Deputy are able to change the settings for hour budgets between Daily and Weekly at will. Data is retained and segmented as appropriate. Due to this it is best practice for integrations to always send the relevant daily timestamp instead of a single post for the week. This allows users the most flexibility when using the feature in Deputy.

Adding hour budgets via the API is a relatively simple option but there is some information you will require before you can successfully save the data:

area - In the Deputy application, this is called an Area. If you want to track hour budgets against a specific Area in Deputy you will need to include this item. In other API requests this is called the OperationalUnit. To get a list of areas use the Get Operational Units endpoint.

timestamp - The timestamp for the hour budget to be set in epoch time. Even if your user is only intending to use weekly not daily budgets, it is important to set the timestamp specifically as users are able to change from weekly to daily budgets at any time.

value - The amount to set as the hour budget. It should be noted that this is not a cumulative calculation and whatever you set will be overwritten. So for example if you had previously set 80 hours and you need it to be 120 hours your request needs to be 120 not 40 as the original 80 will be overwritten.

type - When adding hour budgets the type is budget_hour.

reference - You can choose to set a reference for the record when being saved into the database.

location - This is the location within Deputy where the sale should be attributed. In other API requests you may see this referred to as Company. To get a list of locations use the Get Locations endpoint.

Adding hour budgets via the API


curl --request POST --url 'https://{install}.{geo}
    "data": [
            "timestamp": 1660272300,
            "area": 2,
            "type": "budget_StaffHour",
            "reference": "hours-ManualEntry-1660272300",
            "value": 81,
            "location": 1

If the hour budget data is added successfully, you will get a response including information about the data that was saved, including an id of the record.

    "success": true,
    "data": [
            "timestamp": "1660272300",
            "employee": 0,
            "area": 1,
            "type": "budget_StaffHour",
            "reference": "Hours-ManualEntry-1660272300",
            "value": 81,
            "state": "ACTUAL",
            "location": 1,
            "id": "2TBYvxelKDN1GBoriNkZljJaNZK",
            "created": "2023-07-28T04:22:54Z",
            "modified": "",
            "payload": "{\"timestamp\":1690437981,\"employee\":0,\"area\":1,\"type\":\"budget_StaffHour\",\"reference\":\"Sales-ManualEntry-1660272300\",\"value\":91400.3,\"state\":0,\"location\":1}"

You can also added many hour budgets at once by appending :bulkto the end of the API url. When this is the case just include multiple objects in the array.


Bulk API

When using the bulk API method, the data may not be ready for retrieval or display within Deputy immediately. If you need real-time saving you should use the regular API url

## Data Elements

Data ElementInfo
timestampThe timestamp of the hour budget in unix time
employeeIf the hour budget was saved against an employee id it would appear here. 0 means not saved against employee
areaThe id of the area the hour budget has been saved for
locationThe id of the location the hour budget has been saved for
referenceThe reference that was saved against the hour budget entry
valueThe value of the hour budget
stateIf the state is ACTUAL it means that this is considered the hour budget and not in draft
createdThe created time for the record in zulu time
modifiedThe last modified time for the record in zulu time
payloadDeputy now saves the payload that was sent to the API against the record for troubleshooting purposes. This allows you to see the exact payload that was received into the system.