Retrieving Sales Data from Deputy

Retrieving Sales Data from a Deputy install

Retrieving data from Deputy about sales data is as simple as a GET request with some information about the timeframe and any areas you may want to specifically target.

The URL for this request is https://{deputyinstall}.{geo}.deputy.com/api/v2/metrics/raw?areas=1&types=Sales&start={starttime}&end={endtime}

The start and end times are timestamps in epoch format (unix time).

For example
https://simonssambos.au.deputy.com/api/v2/metrics/raw?areas=1&types=Sales&start=1657461600&end=1658066399 will retrieve the Sales metric from an Area with the id of 1 between the epoch time of 1657461600 and 1658066399.

If you wanted to include multiple areas, you can do so by including them in the URL delimited by commas. For example https://simonssambos.au.deputy.com/api/v2/metrics/raw?areas=1,2&types=Sales&start=1657461600&end=1658066399

The same applies for sales metrics. Lets say that the Deputy install has a metrics for both Sales and Transactions. To retrieve both those metrics at the same time as an example would be
https://simonssambos.au.deputy.com/api/v2/metrics/raw?areas=1,2&types=Sales,Transactions&start=1657461600&end=1658066399

Forecasting

Deputy has two types of sales forecasting in the business insights area of the program. Manager forecast, which is where users enter their forecasts manually into the system and regular forecasts which is where Deputy has auto generated a forecast based on previous sales metrics.

You are able to retrieve these forecasts via the API by prepending either plan or forecast in front of the metric name in the request. So for example if you wanted the manager forecast for the Sales metric you would use plan_Sales whereas if you wanted the Deputy generated forecast you would use forecast_Sales in the type name.

Sample Data

Once you have connected to the API successfully, you will get a response much like the following

{
    "success": true,
    "data": [
        {
            "timestamp": "1657720800",
            "employee": -1,
            "area": 1,
            "type": "sales",
            "reference": "Sales-12-1658053200",
            "value": 65200,
            "state": "ACTUAL",
            "location": 0,
            "id": "",
            "created": "2022-07-14T17:08:31+1000",
            "modified": "2022-07-14T17:08:31+1000"
        },
        {
            "timestamp": "1657753200",
            "employee": -1,
            "area": 1,
            "type": "sales",
            "reference": "DEP-ManualEntry-Sales-1-1657753200-9-0",
            "value": 5433.3333000000002,
            "state": "ACTUAL",
            "location": 0,
            "id": "",
            "created": "2022-07-14T17:08:15+1000",
            "modified": "2022-07-14T17:08:15+1000"
        },
        {
            "timestamp": "1657756800",
            "employee": -1,
            "area": 1,
            "type": "sales",
            "reference": "DEP-ManualEntry-Sales-1-1657756800-10-0",
            "value": 5433.3333000000002,
            "state": "ACTUAL",
            "location": 0,
            "id": "",
            "created": "2022-07-14T17:08:15+1000",
            "modified": "2022-07-14T17:08:15+1000"
        }
      ]
}

The response is an array of metric objects.

Data ElementWhat is this
TimestampThe timestamp of the sale/metric in epoch.
EmployeeThe employee id is attributed to the sale. This will be -1 if it was manually added into the backend of the install
AreaThe area as an integer the sale is attributed to. If you need to find the areas you can use the Get Operational Units endpoint.
TypeThe type of metric returned in that object. For example Sales
ReferenceThe reference for the transaction
ValueThe value of the transaction/metric
stateWhether this metric is an actual amount or a forecast amount.
locationThe location which is attributed to the metric as an integer. If you need to find which integers match which locations you can use the Get Locations endpoint
createdWhen the record was created
modifiedWhen the record was last modified

🚧

Empty Array

If you receive an empty array as the response, it means that no data is available for that metric in the time period specified.