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, negative, or null. If it is not sent or is sent as null, any previously recorded value for that day is deleted.

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.

If no value or null is sent ("value": null), any previously registered value with the same date day is deleted.

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 historical value closest to the end of the counter scope prevails

If there are multiple historical values within the time scope of a counter, Orquest always returns the value closest to the end of that scope.

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
  }
]

Orquest stores historical values and, since THS, THM, and THA share the same counting logic, these historical values may apply to all three counters.

THS (weekly)

For the week of January 24, the value is 60.

For the week of January 31, the value is 240.

THM (monthly)

In January 2026, there are two historical values, but the system uses the one closest to the end of the counter scope: 240.

THA (annual)

In 2026, there are also two values, but the system uses the one closest to the end of the counter scope: 240. If values with a day date later than 2026-01-31 and within the annual scope are recorded, the value of this counter will be updated.

In the scope of a counter, the value with the date closest to the end prevails.

Useful links

What is a counter?