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. If it has been modified, the custom short name must be indicated in this field.

  • 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 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.

Each element in the list is processed independently: valid elements are recorded even if others in the same request are invalid, and the failure of a single one does not discard the rest of the batch.

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.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

400 Bad Request

-

One of the request fields does not have the expected format. It is recommended to validate the date format (yyyy-MM-dd) before sending the request.

Employee not found

The provided employee identifier does not exist in the business. It is recommended to verify the identifier through Get employee information.

No counter of type {counterShortName}

The provided counter short name does not match any counter in the business. It is recommended to check the valid short names through Get active counters for a business.

Useful links

What is a counter?