Reports API (worktime)

The work time report API allows you to retrieve recorded work time hours. The report data is pre-calculated according to the system's calculation settings.

Data can be retrieved either as raw data or formatted according to report configurations predefined in the Deltabit system.

Retrieving reference data

Before fetching report data, you can retrieve reference data from the base endpoint. The following information is returned:

formattedReports: Definitions for pre-formatted reports.
workGroups: Work time groups, used for filtering persons.
departments: Departments, used for filtering persons.
userGroups: User groups, used for filtering persons.

Example

GET /api/v1/reports/worktime

Response:

{
    "formattedReports": [
        { "id": 1, "name": "Payroll export" }
    ],
    "workGroups": [
        { "id": 1, "name": "Flexible work" },
        { "id": 2, "name": "Shift work" }
    ],
    "departments": [
        "Office",
        "Yard"
    ],
    "userGroups": [
        { "id": "72057594037927936", "name": "Common" },
        { "id": "144115188075855872", "name": "Setti" }
    ]
}

Fetching a report

POST /api/v1/reports/worktime

Parameters

Parameter	Required	Description
`startDate`	Yes.	Start date. Format: `YYYY-MM-DD`
`endDate`	Yes.	End date. Format: `YYYY-MM-DD`
`formatted`	No	Formatted report ID or name.

Filters

Parameter	Description
`personNumbers`	List of person IDs to include. Filtering by name is not supported, as names may not be unique.
`workGroups`	List of work time group IDs or names to filter by.
`departments`	List of department names to filter by.
`userGroups`	List of user group IDs or names to filter by. Note: the ID is a bigint and must be provided as a string.
`includeArchived`	If `true` , archived persons are included. Default: `false`
`onlyApproved`	If `true` , only entries approved by a supervisor are included. Default: `false`
`onlyUnexported`	If `true` , only entries that have not been exported are included. Default: `false`

Example: raw data response

POST /api/v1/reports/worktime

Request:

{
    "startDate": "2026-01-01",
    "endDate": "2026-02-01"
}

Response:

{
    "data": [
        {
            "id": 6,
            "balances": [
                {
                    "id": -2,
                    "value": 1800
                }
            ],
            "shifts": [
                {
                    "date": "2026-01-01",
                    "reviewed": {
                        "personId": 16,
                        "dt": "2026-02-01T07:42:44+02:00"
                    },
                    "approved": {
                        "personId": 6,
                        "dt": "2026-03-01T07:42:44+02:00"
                    },
                    "total": [
                        {
                            "id": -1,
                            "value": 28800
                        },
                        {
                            "id": 1,
                            "value": 28800
                        }
                    ]
                }
            ]
        }
    ],
    "persons": [
        { "id": 6, "name": "Smith John" }
    ],
    "salaryTypes": [
        { "id": -1, "name": "Worktime" },
        { "id": 1, "name": "Norm.h" },
        { "id": -2, "name": "flextime" }
    ]
}

Response structure

The response contains the following top-level fields:

data: Array of entries. Each entry contains an id referencing the persons array, a balances array and a shifts array with the recorded time entries.
persons: Lookup array mapping person IDs to names.
salaryTypes: Lookup array mapping salary type IDs to names.

Each balance contains:

id: References the salaryTypes array.
value: Amount in seconds.

Each shift contains:

date: Date of the entry.
total: Salary type breakdown. Each entry has an id referencing the salaryTypes array and a value (seconds).
approved: Returned if the shift is approved.
reviewed: Returned if the shift is reviewed.

Preformatted response

If a pre-configured report format has been defined in the Deltabit system, the response is returned in the configured format instead of raw JSON. The format depends on the report configuration and can be, for example, XML or CSV.

Available preformatted reports and their configurations can be retrieved from the formattedReports field in the reference data response.