Daily Reports

Daily reports (Tagesberichte) document what happened on a construction site or project on a single calendar day: who was on site and for how long, the weather, subcontractors, activities, material usage, comments, photos, and signatures. A report is identified by the combination of a project and a date — it is not a stored object of its own, but materializes from the individual entries recorded for that day, either authored on site in the mobile app or filled in automatically from time tracking.

If your API token is restricted to specific permissions, it needs the matching scope for each operation: daily_reports:view for all GET requests, and daily_reports:edit for the autofill and photo-upload-token endpoints. Autofilling a report that has already been submitted or approved additionally requires daily_reports:approve; autofilling an archived report is rejected outright — it must first be reopened. Requests without the required permission return 403 Forbidden.

Daily reports are authored — and their status changed (submitted, approved, reopened) — in the TimeSec web and mobile apps. Through the API you can read reports and their entries, trigger the time-tracking autofill, download PDFs, and request photo upload tokens. Creating entries and changing a report's status are not currently available for API tokens.

The Report Object#

A report is the group of all entries that share a project and a date. Reports only exist for projects that have daily reports enabled in the project's settings, and only for days that have at least one entry. The tag_id is the project's id as returned by the Projects API.

Every report has a computed status describing its position in the review lifecycle:

draft — the report is being worked on and can be edited on site.
submitted — the site crew handed the report in for review. Only supervisors (users with the approve permission) may still change it.
closed — the report was approved. Like submitted, it is locked for regular editors.
archived — the report was archived by a supervisor. Archived reports are immutable (including the time-tracking autofill) until a supervisor moves them back to draft.

Name	Type	Description
`id`	string	Synthetic identifier of the report in the form `<tag_id>\|<date>`, e.g. `3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31\|2024-06-18`. Read-only.
`date`	string (YYYY-MM-DD)	The calendar day the report covers.
`tag_id`	string (UUID)	The project the report belongs to.
`status`	string	Computed report status: `draft`, `submitted`, `closed`, or `archived`.
`tag`	object or null	The project the report belongs to, as `{id, name, code, color}`, or `null` if the project could not be resolved. Only present in list responses. Read-only.
`address`	string	The project's configured address, or an empty string. Only present in list responses. Read-only.
`cost_center`	string	The project's configured cost center, or an empty string. Only present in list responses. Read-only.
`client`	string	The project's configured client, or an empty string. Only present in list responses. Read-only.
`contributor_count`	integer	Number of distinct users who authored an entry on this report. Only present in list responses. Read-only.
`employees`	array of objects	Employees with `employee-working-times` entries on this report, as `{id, first_name, last_name}`. Only present in list responses. Read-only.
`total_hours`	number	Sum of the `hours` value across the report's `employee-working-times` entries. Only present in list responses. Read-only.
`weather`	array of objects	The report's captured weather readings, sorted by `time`. Each object has the same shape as the `weather` entry value fields. Only present in list responses. Read-only.
`values`	array of objects	The report's newest visible value per field type (not per group), each carrying that field's type-specific value fields plus a `type` key. Lets an overview client render a report card without a follow-up request to the entries endpoint. Only present in list responses. Read-only.

Field Configurations#

Which fields a daily report contains is configurable per organization, and the configuration is versioned by date. Your organization keeps a list of configurations, each with a valid_from date; the configuration that applies to a report is the one with the most recent valid_from on or before the report's date (a configuration becomes active on its valid_from day).

A report whose date lies before every stored valid_from uses your organization's oldest configuration. The first version is written when daily reports are switched on, so reports for days before that switch match no version at all — they are rendered with the oldest field set your organization ever had, not with the built-in default form. The default form below applies only to organizations that have no configuration at all:

Field id	Type	Label (German)
`weather`	`weather`	Witterung
`employee-working-times`	`employee-working-times`	Mitarbeitende
`subcontractors`	`subcontractors`	Nachunternehmen
`activities`	`activities`	Tätigkeiten
`materials`	`string`	Material- / Geräteeinsatz
`comments`	`string`	Bemerkungen / Behinderungen
`photos`	`image`	Fotos
`signatures`	`signature`	Unterschriften

Versioning has two consequences you will notice in the API:

Every entry is interpreted and validated against the configuration that is active on the entry's date, not the one active today. Historical reports keep the form they were written with, even after the organization changes its report layout.
Entries whose field id does not exist in the configuration active for their date (for example, a field that was later removed) are omitted from entry listings and PDFs — they have no schema to render.

Use the field-types endpoint to discover the available field types and how entries of each type are grouped.

The Entry Object#

Entries are append-only: nothing is ever updated in place. Each entry belongs to a logical group identified by its group_id, which combines the report's date and tag_id with type-specific keys (for example, one group per employee for working times, or one group per author-and-text for comments). The most recent entry of a group is its current value; older entries are the group's history. An entry with burned: true is a tombstone that marks its group as deleted.

Entries written by the system — the time-tracking autofill and the automatic weather capture — have author_id: null; the affected employee is carried in on_behalf_of_id. Manually authored entries carry the author, and on_behalf_of_id names the person the entry is about (e.g. who signed, or whose working time was corrected).

Name	Type	Description
`id`	string (UUID)	Unique identifier of the entry. Read-only.
`group_id`	string	Pipe-separated grouping key, starting with `date` and `tag_id` followed by the field type's grouping values. Read-only.
`group_count`	integer	Number of entries in this entry's group that match the request's filters, including tombstones — filtering by `ids` excludes the group's other entries from the count. Only present in list responses. Read-only.
`field_id`	string	Id of the report field the entry belongs to, as defined in the active field configuration (e.g. `comments`).
`type`	string	The field's type: `weather`, `employee-working-times`, `subcontractors`, `activities`, `string`, `image`, or `signature`.
`date`	string (YYYY-MM-DD)	The report day the entry belongs to.
`tag_id`	string (UUID)	The project the entry belongs to.
`author_id`	string (UUID) or null	The user who authored the entry, or `null` for system-generated entries (autofill, weather capture).
`author_name`	string or null	Full name of the author, or `null`.
`on_behalf_of_id`	string (UUID) or null	The user the entry is about (e.g. the employee whose hours are recorded, or the person who signed), or `null`.
`on_behalf_of_name`	string or null	Full name of the `on_behalf_of` user, or `null`.
`burned`	boolean	`true` marks the entry as a tombstone: the group it belongs to should be treated as deleted if the tombstone is the group's latest entry.
`submitted_at`	string (ISO 8601, local time) or null	When the entry reached the server, e.g. `2024-06-18T16:42:07`. `null` for system-generated entries.
`created_at`	string (ISO 8601, local time)	When the entry was stored. Read-only.
`modified_at`	string (ISO 8601, local time)	When the entry was last modified. Read-only.

Type-specific value fields#

In addition to the common properties above, each entry carries the value fields of its type:

weather — time (string, a clock time such as 08:00), temperature (number or null), and weather_condition: one of sunny, cloudy, precipitation or snow, or null when the reading carries no usable condition. The four categories are the ones listed under choices.condition in the field types response. Grouped by time, so a report holds one weather row per configured time slot.

Writes may additionally carry precipitation and cloud_cover (numbers) and wind (a [speed, direction] pair with the direction in degrees 0–359). Those keys are still validated and stored, but reads no longer return them. Automatically captured readings are reduced the same way: the weather provider's detailed response stays server-side and is folded into the single weather_condition category.
employee-working-times — hours (number between 0 and 24), plus a snapshot of the employee at the time the entry was written: employee_account_id (string), employee_name (string), and employee_position (string, from the employee's position custom field; empty string if unset). The snapshot keeps the report accurate even if the employee's account or custom fields change later. Grouped by on_behalf_of_id: one row per employee and day.
subcontractors — name (string), employees (integer), hours (number or null), comment (string or null). Grouped by on_behalf_of_id and name.
activities — text (string). Grouped by on_behalf_of_id and text, so the same activity text for the same person deduplicates.
string — value (string). Used by the default materials and comments fields. Grouped by on_behalf_of_id and value.
image — image_id (string), image_key (string or null, the S3 object key from the photo upload flow), image_url (string or null — a pre-signed download URL derived from image_key, valid for one hour), thumb_key (string or null, the object key of the downscaled preview), thumb_url (string or null — a pre-signed download URL derived from thumb_key, valid for one hour), latitude / longitude (numbers or null), and taken_at (string or null). Grouped by on_behalf_of_id and image_id. thumb_key and thumb_url are null for entries whose client did not upload a preview; fall back to image_url in that case.
signature — image (string, a data:image/... data URL of the signature). Grouped by on_behalf_of_id: one signature per person per report.

List all Reports#

GET/api/v2/daily-reports/reports/

Retrieve paginated report descriptors for projects and dates containing entries. Results ordered by date descending, then project id.

Query Parameters#

Name	Type	Description
`date_from`	string (YYYY-MM-DD)	Include reports on or after this date
`date_to`	string (YYYY-MM-DD)	Include reports on or before this date
`daterange`	string	Inclusive range format `YYYY-MM-DD\|YYYY-MM-DD`
`projects`	string	Pipe-separated project UUIDs to filter
`status`	string	Pipe-separated statuses: `draft`, `submitted`, `closed`, `archived`
`limit`	integer	Results per page (default 100, max 1000)
`offset`	integer	Results to skip (default 0)

Request#

cURL

curl -X GET "https://api.timesec.de/api/v2/daily-reports/reports/?date_from=2024-06-17&date_to=2024-06-18&status=draft|submitted" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response#

JSON

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|2024-06-18",
      "date": "2024-06-18",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "status": "submitted",
      "tag": {
        "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
        "name": "Neubau Lagerhalle",
        "code": "P-2024-018",
        "color": "#2563eb"
      },
      "address": "Industriestraße 12, 44269 Dortmund",
      "cost_center": "4711",
      "client": "Musterbau GmbH",
      "contributor_count": 2,
      "employees": [
        {
          "id": "508d5250-7399-4b65-a574-3da53d9ddc25",
          "first_name": "Anna",
          "last_name": "Schmidt"
        }
      ],
      "total_hours": 7.75,
      "weather": [
        {
          "time": "08:00",
          "temperature": 14.2,
          "weather_condition": "cloudy"
        }
      ],
      "values": [
        {
          "type": "weather",
          "time": "08:00",
          "temperature": 14.2,
          "weather_condition": "cloudy"
        },
        {
          "type": "employee-working-times",
          "on_behalf_of_id": "508d5250-7399-4b65-a574-3da53d9ddc25",
          "on_behalf_of_name": "Anna Schmidt",
          "hours": 7.75
        }
      ]
    },
    {
      "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|2024-06-17",
      "date": "2024-06-17",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "status": "draft",
      "tag": {
        "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
        "name": "Neubau Lagerhalle",
        "code": "P-2024-018",
        "color": "#2563eb"
      },
      "address": "Industriestraße 12, 44269 Dortmund",
      "cost_center": "4711",
      "client": "Musterbau GmbH",
      "contributor_count": 0,
      "employees": [],
      "total_hours": 0,
      "weather": [],
      "values": []
    }
  ]
}

List Field Types#

GET/api/v2/daily-reports/reports/field-types/

Retrieve available field types, their grouping keys, and human-readable descriptions. Each type includes choice lists for fixed-value fields.

Request#

cURL

curl -X GET "https://api.timesec.de/api/v2/daily-reports/reports/field-types/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response#

JSON

{
  "count": 7,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "weather",
      "group_by": [
        "date",
        "tag_id",
        "time"
      ],
      "description": "Weather readings for configured local report times.\n\nConfig: requires `times`, a list of HHMM strings such as `[\"0800\"]`, and\n`autofill_from_api`, a boolean that controls weather autofill from an API.",
      "choices": {
        "condition": [
          {
            "id": "sunny",
            "label": "Sonnig"
          },
          {
            "id": "cloudy",
            "label": "Bewölkt"
          },
          {
            "id": "precipitation",
            "label": "Niederschlag"
          },
          {
            "id": "snow",
            "label": "Schnee"
          }
        ]
      }
    },
    {
      "id": "employee-working-times",
      "group_by": [
        "date",
        "tag_id",
        "on_behalf_of_id"
      ],
      "description": "Working-time totals for employees contributing to a daily report.\n\nConfig: requires `autofill_from_tracking`, a boolean that controls whether\ntracked working times are imported automatically.",
      "choices": {}
    },
    {
      "id": "subcontractors",
      "group_by": [
        "date",
        "tag_id",
        "on_behalf_of_id",
        "name"
      ],
      "description": "Per-day list of subcontractor companies present on a project.\n\nConfig: no options are supported; pass `{}` or omit the config.\nValues require `name` and `employees`; `hours` and `comment` are optional.",
      "choices": {}
    },
    {
      "id": "activities",
      "group_by": [
        "date",
        "tag_id",
        "on_behalf_of_id",
        "text"
      ],
      "description": "Activity notes for work performed on a daily report.\n\nConfig: requires `autofill_from_tracking`, a boolean that controls whether\ntime-tracking comments are imported automatically.",
      "choices": {}
    },
    {
      "id": "string",
      "group_by": [
        "date",
        "tag_id",
        "on_behalf_of_id",
        "value"
      ],
      "description": "Free-text report entry used for configurable text fields.\n\nConfig: no options are supported; pass `{}` or omit the config.",
      "choices": {}
    },
    {
      "id": "image",
      "group_by": [
        "date",
        "tag_id",
        "on_behalf_of_id",
        "image_id"
      ],
      "description": "Photo attachment for a daily report, including optional capture metadata.\n\nConfig: no options are supported; pass `{}` or omit the config.",
      "choices": {}
    },
    {
      "id": "signature",
      "group_by": [
        "date",
        "tag_id",
        "on_behalf_of_id"
      ],
      "description": "Signature image captured for a report participant.\n\nConfig: no options are supported; pass `{}` or omit the config.",
      "choices": {}
    }
  ]
}

Retrieve Report Status#

GET/api/v2/daily-reports/reports/status/

Get the current status of a single report. A report without status transitions defaults to draft.

Query Parameters#

Name	Type	Description
`tag`	string (UUID)	Project id (required)
`date`	string (YYYY-MM-DD)	Report date (required)

Request#

cURL

curl -X GET "https://api.timesec.de/api/v2/daily-reports/reports/status/?tag=3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31&date=2024-06-18" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response#

JSON

{
  "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
  "date": "2024-06-18",
  "status": "submitted"
}

Autofill a Report#

POST/api/v2/daily-reports/reports/autofill/

Compute and store entries from daily time tracking. Only fields configured with autofill_from_tracking are populated: employee working times and activities. The operation is idempotent; manually corrected values are preserved.

Body Parameters#

Name	Type	Description
`tag`	string (UUID)	Project id (required)
`date`	string (YYYY-MM-DD)	Report date (required)
`field`	string	Optional field id to restrict autofill

Request#

cURL

curl -X POST "https://api.timesec.de/api/v2/daily-reports/reports/autofill/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
    "date": "2024-06-18"
  }'

Response#

JSON

{
  "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
  "date": "2024-06-18",
  "filled": [
    "employee-working-times",
    "activities"
  ]
}

Download a Report PDF#

GET/api/v2/daily-reports/reports/:id/pdf/

Render a report as a print-friendly PDF. The ID format is <tag_id>|<date>, with | sent literally or percent-encoded as %7C. Response streams PDF binary with filename Tagesbericht-<project code>-<date>.pdf.

Request#

cURL

curl -X GET "https://api.timesec.de/api/v2/daily-reports/reports/3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31%7C2024-06-18/pdf/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o "Tagesbericht-2024-06-18.pdf"

List all Entries#

GET/api/v2/daily-reports/entries/

Retrieve paginated report entries filtered through active field configurations. Use grouped=1 to show only the most recent entry per group.

Query Parameters#

Name	Type	Description
`tags`	string	Pipe-separated project UUIDs
`field_id`	string	Filter to one configured field
`daterange`	string	Inclusive range `YYYY-MM-DD\|YYYY-MM-DD`
`grouped`	string	Set to `1` for most recent entry per group
`ids`	string	Pipe-separated entry UUIDs
`limit`	integer	Results per page (default 100, max 1000)
`offset`	integer	Results to skip (default 0)

Request#

cURL

curl -X GET "https://api.timesec.de/api/v2/daily-reports/entries/?tags=3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31&daterange=2024-06-18|2024-06-18&grouped=1" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response#

JSON

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "group_id": "2024-06-18|3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|508d5250-7399-4b65-a574-3da53d9ddc25",
      "id": "6b0f2d84-3c9e-4f17-8a52-b1d4e7c90a63",
      "field_id": "employee-working-times",
      "type": "employee-working-times",
      "created_at": "2024-06-18T17:02:11",
      "modified_at": "2024-06-18T17:02:11",
      "submitted_at": null,
      "date": "2024-06-18",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "author_id": null,
      "on_behalf_of_id": "508d5250-7399-4b65-a574-3da53d9ddc25",
      "author_name": null,
      "on_behalf_of_name": "Anna Schmidt",
      "burned": false,
      "hours": 7.75,
      "group_count": 1
    },
    {
      "group_id": "2024-06-18|3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|e7c9a4d2-1f38-4b6a-9c05-8d2f7b3e6a14|Lieferung Schalholz verspätet",
      "id": "9d47c1f0-5e2b-4a86-b3f9-0c61d8a24e57",
      "field_id": "comments",
      "type": "string",
      "created_at": "2024-06-18T16:42:09",
      "modified_at": "2024-06-18T16:42:09",
      "submitted_at": "2024-06-18T16:42:07",
      "date": "2024-06-18",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "author_id": "e7c9a4d2-1f38-4b6a-9c05-8d2f7b3e6a14",
      "on_behalf_of_id": "e7c9a4d2-1f38-4b6a-9c05-8d2f7b3e6a14",
      "author_name": "Jonas Weber",
      "on_behalf_of_name": "Jonas Weber",
      "burned": false,
      "value": "Lieferung Schalholz verspätet",
      "group_count": 1
    }
  ]
}

Get a Photo Upload Token#

POST/api/v2/daily-reports/entries/upload-photo-token/

Generate pre-signed S3 upload credentials for daily-report photos (max 2 MB). Response includes form fields for uploading both full-size and thumbnail versions, valid for 12 hours.

Body Parameters#

Name	Type	Description
`filename`	string	File name for storage key
`filetype`	string	MIME type (e.g., `image/jpeg`)
`filesize`	integer	File size in bytes (max 2097152)

Request#

cURL

curl -X POST "https://api.timesec.de/api/v2/daily-reports/entries/upload-photo-token/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "betonage-nord",
    "filetype": "image/jpeg",
    "filesize": 2048576
  }'

Response#

JSON

{
  "url": "https://s3.eu-central-1.amazonaws.com/timesec-uploads",
  "fields": {
    "key": "i-f4a5b6c7-d8e9-0123-fabc-456789012345/u-a1b2c3d4-e5f6-7890-abcd-ef1234567890/daily-reports/2024/06/18/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-18_4f2a_betonage-nord.jpg",
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMDYtMTlUMDY6MzA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
    "signature": "hV0kwGx0ZQKgQnJ1zW0m9dEXAMPLE"
  },
  "thumb_fields": {
    "key": "i-f4a5b6c7-d8e9-0123-fabc-456789012345/u-a1b2c3d4-e5f6-7890-abcd-ef1234567890/daily-reports/2024/06/18/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-18_4f2a_betonage-nord.thumb.jpg",
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMDYtMTlUMDY6MzA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
    "signature": "yQ2mNpR7bTfLc0aVzX4jE9EXAMPLE"
  }
}