Time Balances

The following endpoints allow importing work time and vacation time balances. 

WORK_TIME_BALANCE = WORKED_TIME - MANDATORY_WORKING_TIME
VACATION_BALANCE  = GUARANTEED_VACATION_DAYS - USED_VACATION_DAYS

An imported balance overrides Bezala's own calculations up to and including the time balance date.

Example. In Finland, the vacation year is calculated from April 1 to March 31. So if the user has, for example, 4 unused vacation days from the last year as of April 1, a vacation balance with the value of 4 and dated March 31 should be imported into Bezala.

>>>

GET /api/users/:user_id/time_balances
Get user's work time & vacation balances

Get a list of imported work time and vacation balances for the specified user.

Examples

{
  "collection": [
    {
      "id": 2,
      "user_id": 819,
      "balance_type": "vacation",
      "date": "2025-03-31",
      "value": 5.0,
      "units": "days",
      "creator_id": 42,
      "creator_name": "John Smith"
    },
    {
      "id": 1,
      "user_id": 819,
      "balance_type": "work_time",
      "date": "2025-03-15",
      "value": 75,
      "units": "minutes",
      "creator_id": 42,
      "creator_name": "John Smith"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2
  }
}

Params

Param name Description
user_id
required

User ID.

Validations:

  • Must be a Integer
balance_type
optional

Filter time entries by the specified balance type.

Validations:

  • Must be one of: work_time, vacation.
page
optional

Page number.

Validations:

  • Must be a Integer
per_page
optional

Number of records per page. Default: 50.

Validations:

  • Must be a Integer
sort_by
optional

Sort by field. Default: date.

Validations:

  • Must be a String
order
optional

Sorting order (descending or ascending). Default: desc.

Validations:

  • Must be one of: desc, asc.
>>>

GET /api/users/:user_id/time_balances/latest
Get latest imported balance

Get the latest imported time balance for the specified user.

Examples

{}
{
  "id": 2,
  "user_id": 819,
  "balance_type": "vacation",
  "date": "2025-03-31",
  "value": 5.0,
  "units": "days",
  "creator_id": 42,
  "creator_name": "John Smith"
}

Params

Param name Description
user_id
required

User ID.

Validations:

  • Must be a Integer
balance_type
optional

Get the latest balance of the specified balance type.

Validations:

  • Must be one of: work_time, vacation.
>>>

POST /api/users/:user_id/time_balances
Import a time balance for the user

Params

Param name Description
user_id
required

User ID.

Validations:

  • Must be a Integer
time_balance
required

Time balance parameters.

Validations:

  • Must be a Hash
time_balance[balance_type]
required

Balance type: work_time or vacation.

Validations:

  • Must be one of: work_time, vacation.
time_balance[date]
required

Date of time balance calculation. The value of the balance is the value as of the end of the specified day.

Validations:

  • Must be a String
time_balance[value]
required

The value of the imported time balance. Can be either positive or negative.

Balance type Units Accepted values
work_time minutes integer
vacation days integer / floating-point

Validations:

  • Must be a Numeric
>>>

DELETE /api/users/:user_id/time_balances/:id
Delete a time balance for the user

Params

Param name Description
user_id
required

User ID

Validations:

  • Must be a Integer
id
required

Time balance ID

Validations:

  • Must be a Integer