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

  • value: value registered in the counter. It can be positive, negative, or null. If it is not sent or is sent as null, any previously recorded value with the same date toDay is deleted.

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 no value or null is sent ("value": null), any previously registered value with the same date toDay is deleted.

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

Elements are grouped by employee: if one of an employee’s values is invalid, the entire batch for that employee is discarded, even if the remaining values were correct. The failure of one employee does not affect the other employees included in the same request.

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 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 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 the historical values 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.

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?