Add counter historical values for periods

This endpoint allows registering a list of counter historical values for periods. Each element in the list represents a value for an employee, a counter, and a specific period, 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-period-values

Below are the fields that make up the request body.

Required fields are marked with an asterisk (*).

Request body

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

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

  • fromDay*: first day of the interval for which the value is registered, in yyyy-MM-dd format.

  • toDay*: last day of the interval for which the value is registered, in yyyy-MM-dd format.

  • counterShortName*: counter short name.

  • value: value registered in 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-period-values
[
    {
        "employeeId": "0001",
        "fromDay": "2026-02-09",
        "toDay": "2026-02-15",
        "counterShortName": "THS",
        "value": -120
    }
]

If all the request data is correct, the historical value of the counter associated with the employee will be stored in the system with the corresponding date.

Considerations

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 date format sent in the fromDay or toDay fields is not correct, the request will return a 400 Bad Request error.

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 registered in 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 registered 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 registered within the scope period.

View example

If the request is made with the following values:

[
    {
        "employeeId": "0002",
        "fromDay": "2026-02-02",
        "toDay": "2026-02-08",
        "counterShortName": "THS",
        "value": 240
    },
    {
        "employeeId": "0002",
        "fromDay": "2026-02-09",
        "toDay": "2026-02-15",
        "counterShortName": "THS",
        "value": 120
    }
]

Orquest registers two historical values per period and, in both cases, the date used as a reference is toDay:

  • 2026-02-08 → 240

  • 2026-02-15 → 120

Since THS, THM, and THA share the same counting logic, these historical values can apply to all three counters.

THS (weekly)

For the week from the 2nd to the 8th, the value will be 240.

For the week from the 9th to the 15th, the value will be 120.

THM (monthly)

In February 2026, there are two historical values, but the system uses the most recent one: 120. If values are registered with a toDay date later than 2026-02-15 and within the monthly scope, this value will be updated.

THA (yearly)

In 2026, there are also several historical values within the year, but the system uses the most recent one: 120. If values are registered with a toDay date later than 2026-02-15 and within the yearly scope, this value will be updated.

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

Useful links

What is a counter?