Hours Account

List of valid entry attributes:

Attribute	Description	Specifics
date	Date that the entry refers to - calculations are done in the account’s business timezone (Europe/Berlin by default)	ISO-8601 formatted date (string), always set
target_seconds	The time the user is supposed to work on the given date based on the user’s working time model(s)	duration in seconds (integer), always set
actual_seconds	The time the user has worked on the given date based on the user’s confirmed time trackings	duration in seconds (integer), always set
absent_seconds	The time the user was/is supposed to work on the given date but has/will not because of an absence	duration in seconds (integer), always set
balance_seconds	The change to the user’s total time balance on the given date	duration in seconds (integer), always set

List

Example response:

{
  "data": [
    {
      "id": "2026-01-01",
      "type": "hours_account",
      "attributes": {
        "date": "2026-01-01",
        "target_seconds": 28800,
        "actual_seconds": 28080,
        "absent_seconds": 0,
        "balance_seconds": -720
      }
    },
    ...
    {
      "id": "2026-01-31",
      "type": "hours_account",
      "attributes": {
        "date": "2026-01-31",
        "target_seconds": 28800,
        "actual_seconds": 28860,
        "absent_seconds": 0,
        "balance_seconds": 60
      }
    }
  ]
}

This endpoint returns the hours account entries for a user in a given time frame.

Hinweis

The endpoint doesn’t necessarily return all entries in the specified date range at once because data still goes through our pagination mechanism. To get all entries from the desired date range, make sure to request all pages or increase the page size to something that guarantees that all dates in the range fit on one page (e.g. 31 if you’re getting data for one month).

HTTP Request

GET /api/v1/users/:user_id/hours_account_entries

Parameter	Description
user_id	ID of the user for whom to list hours account entries.

The following query parameters are mandatory:

Parameter	Description
start_date	The start date of the date range for which to list hours account entries.
end_date	The end date (inclusive) of the date range for which to list hours account entries.

Example: GET /api/v1/users/user-1/hours_account_entries?start_date=2026-01-01&end_date=2026-01-31

Balance

List of valid balance attributes:

Attribute	Description	Specifics
end_date	End of the cumulative balance range (inclusive)	ISO-8601 formatted date (string), always set
from_date	Start of the period totals (inclusive); see behaviour below	ISO-8601 formatted date (string) or null
total_balance_seconds	Cumulative balance from the user’s trackable history start through end of yesterday in the account timezone (today excluded)	duration in seconds (integer), always set
opening_balance_seconds	Cumulative balance before from_date (excluding the first day of the period) through end of yesterday in the account timezone (today excluded); 0 when the filter predates trackable history	duration in seconds (integer), always set
period_balance_seconds	Balance change from from_date through end_date	duration in seconds (integer), always set
period_target_seconds	Sum of target seconds in the period	duration in seconds (integer), always set
period_actual_seconds	Sum of actual seconds from confirmed time trackings in the period	duration in seconds (integer), always set
period_absent_seconds	Sum of absent seconds in the period	duration in seconds (integer), always set

This endpoint returns cumulative and period hours account balances for a user. total_balance_seconds always covers the user’s full trackable history through end of yesterday in the account timezone (today excluded). opening_balance_seconds covers trackable history before from_date through end of yesterday in the account timezone (today excluded). period_* fields cover from_date through end_date when from_date is sent. When from_date is omitted, they cover trackable history through end of yesterday in the account timezone (today excluded), matching total_balance_seconds.

When from_date is omitted, it defaults to the user’s trackable history start (earliest working time model or confirmed time tracking). In that case, period_balance_seconds equals total_balance_seconds.

When from_date is sent but lies before the user’s trackable history start, the response echoes the effective start date (history start), not the raw query parameter.

If the user has no trackable history, from_date is null and all numeric fields are 0.

Example response with from_date (second half of June — employee is 30 minutes ahead in this period; +2 hours overall):

{
  "data": {
    "id": "2026-06-30",
    "type": "hours_account_balance",
    "attributes": {
      "end_date": "2026-06-30",
      "from_date": "2026-06-16",
      "total_balance_seconds": 7200,
      "opening_balance_seconds": 5400,
      "period_balance_seconds": 1800,
      "period_target_seconds": 316800,
      "period_actual_seconds": 318600,
      "period_absent_seconds": 0
    }
  }
}

Example response without from_date (defaults to history start — full month of June, +2 hours overall):

{
  "data": {
    "id": "2026-06-30",
    "type": "hours_account_balance",
    "attributes": {
      "end_date": "2026-06-30",
      "from_date": "2026-06-01",
      "total_balance_seconds": 7200,
      "opening_balance_seconds": 0,
      "period_balance_seconds": 7200,
      "period_target_seconds": 633600,
      "period_actual_seconds": 640800,
      "period_absent_seconds": 0
    }
  }
}

HTTP Request

GET /api/v1/users/:user_id/hours_account_balance

Parameter	Description
user_id	ID of the user for whom to fetch the balance.

The following query parameters are mandatory:

Parameter	Description
end_date	The end date (inclusive) through which to calculate the period balance.

The following query parameter is optional:

Parameter	Description
from_date	Start of the period (inclusive). Defaults to the user’s trackable history start when omitted.

Example with period: GET /api/v1/users/user-1/hours_account_balance?end_date=2026-06-30&from_date=2026-06-16

Example without from_date: GET /api/v1/users/user-1/hours_account_balance?end_date=2026-06-30