Add counter historical values

This endpoint allows adding a list of counter historical values. Each element in the list represents a value for an employee, a counter, and a specific day, and it will be stored in the system as historical data according to the period corresponding to the counter’s scope.

PUT /api/v2/businesses/{businessId}/counter-historical-values

Below are the fields that make up the request body.

Mandatory fields are marked with an asterisk (*).

Request body

JSON analysis 
[
  {
    "day": "string",
    "employeeId": "string",
    "counterShortName": "string",
    "value": 0
  }
]
Details

  • day*: day for which the value is added, in yyyy-MM-dd format.

  • employeeId*: external identifier of the employee for whom the value is added.

  • counterShortName*: counter short name.

  • value: value added into the counter. It can be positive or negative.

Request example

Once the different fields have been analyzed, an example request is shown:

PUT /api/v2/businesses/BUSINESSID/counter-historical-values
[
  {
    "day": "2026-01-30",
    "employeeId": "0001",
    "counterShortName": "THS",
    "value": 120
  }
]

If all the request data is correct, the different values will be stored in the system as historical values associated with the employee and the counter specified in each element.

Considerations

If the date format sent in the day field is not correct, the request will return a 400 Bad Request error.

If the employee identifier does not match any employee in the business, the request will return a 404 Not Found error indicating Employee not found in the message.

If the short name does not match any counter in the business, the request will return a 400 Bad Request error indicating No counter of type X in the message.

The maximum number of elements allowed in this request is 4000.

If the list contains multiple invalid elements, the API returns only the first error encountered and does not insert the remaining elements.

A historical value can affect multiple counters

In Orquest, there are counters that, although they have different names, share the same internal logic (counting method) and differ only in their scope (time range). For example, the following counters:

  • THS: total weekly hours, weekly scope.

  • THM: total monthly hours, monthly scope.

  • THA: total yearly hours, yearly scope.

When a historical value is added into any of them (for example, THS), that value is considered a valid historical value for the entire set (THS, THM, THA, etc.), as long as it applies within the calculated period in each case.

Even if a value is added using a specific counter, that historical value may apply when querying other counters of the same class.

The most recent historical value prevails

If there are multiple historical values within a counter’s time scope, Orquest always returns the most recent one. Thus, the value shown in the web application or via API corresponds to the latest historical value recorded within the scope period.

View example

If the following values are sent for THS (total weekly hours):

[
  {
    "day": "2026-01-24",
    "employeeId": "0001",
    "counterShortName": "THS",
    "value": 60
  },
  {
    "day": "2026-01-31",
    "employeeId": "0001",
    "counterShortName": "THS",
    "value": 240
  }
]

The value of the counter THM (total monthly hours) will be 240, because Orquest takes the last historical value within the counter period, in this case, the one recorded for the last day of the month 2026-01-31.

Within the same period, the historical value with the most recent date always prevails.

Useful links

What is a counter?