Reports API

The project report API allows you to retrieve hours recorded for projects or tasks. 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:

reports: Available reports. A report ID or name is required for fetching report data.
formattedReports: Definitions for pre-formatted reports.
workGroups: Work groups, used for filtering persons.
departments: Departments, used for filtering persons.
userGroups: User groups, used for filtering persons.

Example

GET /api/v1/reports/projects

Response:

{
    "reports": [
        { "id": 1, "name": "Location" }
    ],
    "formattedReports": [
        { "id": 1, "name": "Custom locations" }
    ],
    "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/projects

Parameters

Parameter	Required	Description
`report`	Yes	Report ID or name.
`startDate`	Yes	Start date. Format: `YYYY-MM-DD`
`endDate`	Yes	End date. Format: `YYYY-MM-DD`
`groupBy`	No	Grouping of the response. Possible values: `person` , `date` , `class` . Default: `person`
`includeWork`	No	If `true` , working times from entries are calculated. Default: `false`
`formatted`	No	If `true` , formatted report is used instead. Default: `false`

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 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/projects

Request:

{
    "report": "Location",
    "startDate": "2026-01-01",
    "endDate": "2026-02-01",
    "includeWork": true
}

Response:

{
    "data": [
        {
            "id": 6,
            "periods": [
                {
                    "length": 9807,
                    "date": "2026-01-01",
                    "start": "2026-01-01T07:42:44+02:00",
                    "end": "2026-01-01T10:26:11+02:00",
                    "classes": [
                        {
                            "id": 6,
                            "length": 9807,
                            "question": 1
                        },
                        {
                            "id": 8,
                            "length": 9807,
                            "question": 2
                        },
                        {
                            "value": "3",
                            "length": 9000,
                            "question": 323
                        }
                    ],
                    "salaryTypes": [
                        {
                            "id": -1,
                            "length": 9807
                        },
                        {
                            "id": 1,
                            "length": 9807
                        },
                        {
                            "id": -4,
                            "length": 0
                        }
                    ]
                }
            ]
        }
    ],
    "classes": [
        { "id": 6, "name": "Warehouse" },
        { "id": 8, "name": "Stock" }
    ],
    "persons": [
        { "id": 6, "name": "Jokinen Hilma" }
    ],
    "questions": [
        { "id": 1, "name": "Location" },
        { "id": 2, "name": "Task" }
    ],
    "salaryTypes": [
        { "id": -1, "name": "Worktime" },
        { "id": 1, "name": "Norm.h" },
        { "id": -4, "name": "Meal break" }
    ]
}

Response structure

The response contains the following top-level fields:

data: Array of entries grouped by person (default). Each entry contains an id referencing the persons array and a periods array with the recorded time entries.
persons: Lookup array mapping person IDs to names.
questions: Lookup array mapping question IDs to names. Questions represent the classification categories (e.g. "Location", "Task").
salaryTypes: Lookup array mapping salary type IDs to names.

Each period contains:

length: Duration in seconds.
date: Date of the entry.
start / end: Start and end timestamps with time zone.
classes: Classification of the period. Each class has an id , length (seconds), and a question referencing the questions array.
salaryTypes: Salary type breakdown. Each entry has an id referencing the salaryTypes array and a length (seconds). Only included when includeWork is true .

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.