Absences

Absences represent periods when an employee is not working, such as vacation, sick leave, parental leave, or other types of time off. Each absence is linked to an employee and has a configurable type that determines how it affects working time calculations.

The Absence Object

Name
id
Type
string (UUID)
Description
Unique identifier for the absence.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the absence was created.
Name
modified_at
Type
string (ISO 8601)
Description
Timestamp when the absence was last modified.
Name
employee_id
Type
string (UUID)
Description
The employee this absence belongs to.
Name
date_from
Type
string (YYYY-MM-DD)
Description
Start date of the absence.
Name
date_to
Type
string (YYYY-MM-DD)
Description
End date of the absence (inclusive).
Name
affected_days
Type
decimal (string)
Description
Number of working days affected by this absence. Returned as a string with three decimal places (e.g. "5.000").
Name
missing_type
Type
string
Description
The absence type identifier (e.g. holiday, sickday). Configured per organization — retrieve the available values via List Absence Types.
Name
target_hour_behaviour
Type
string
Description
How this absence affects target working hours. Valid values: substract_from_target_hours (the absence reduces the day's target hours) and add_to_debit_hours (the absence is credited as worked time). See also List Target Hour Behaviours.
Name
comment
Type
string
Description
A note or description for the absence.
Name
attachment
Type
string
Description
S3 object key of an attached file (e.g. doctor's note). Multiple files are joined with |. This is not a downloadable URL — pass the key to Sign an Attachment URL to obtain a temporary download link.
Name
additional_fields
Type
object
Description
Custom key-value data. Only keys that are configured as custom fields for your organization are accepted.

GET/api/v2/timestamps/absence/

List all Absences

Retrieve a paginated list of absences. This endpoint uses limit/offset pagination with a default page size of 1000 and a maximum of 20000.

Query Parameters

Name
daterange
Type
string
Description
Filter by date range: YYYY-MM-DD|YYYY-MM-DD. Returns absences that overlap with the range. Either side may be omitted for an open-ended range (e.g. 2024-06-01| or |2024-06-30).
Name
created_at
Type
string
Description
Filter by creation date range: YYYY-MM-DD|YYYY-MM-DD. Either side may be omitted for an open-ended range.
Name
ids
Type
string
Description
Filter by absence IDs, pipe-separated.
Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.
Name
employee_group_ids
Type
string
Description
Filter by employee group IDs, pipe-separated. Use null for ungrouped.
Name
missing_types
Type
string
Description
Filter by absence types, pipe-separated (e.g. holiday|sickday).
Name
has_attachment
Type
boolean
Description
Filter by presence of an attachment.
Name
order
Type
string
Description
Sort by created_at (default), date_from, or date_to. Prefix a field with - for descending order and combine multiple fields with | (e.g. -date_from|created_at).
Name
limit
Type
integer
Description
Maximum number of results per page. Defaults to 1000, capped at 20000.
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/?daterange=2024-06-01|2024-06-30&missing_types=holiday" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "created_at": "2024-05-15T10:00:00",
      "modified_at": "2024-05-15T10:00:00",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "date_from": "2024-06-10",
      "date_to": "2024-06-14",
      "affected_days": "5.000",
      "missing_type": "holiday",
      "target_hour_behaviour": "substract_from_target_hours",
      "comment": "Summer vacation",
      "attachment": null,
      "additional_fields": {}
    }
  ]
}

GET/api/v2/timestamps/absence/:id/

Retrieve an Absence

Get details of a specific absence.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/c1d2e3f4-a5b6-7890-cdef-123456789012/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/timestamps/absence/

Create an Absence

Create a new absence for an employee.

Required Parameters

Name
employee_id
Type
string (UUID)
Description
The employee to create the absence for.
Name
date_from
Type
string (YYYY-MM-DD)
Description
Start date.
Name
date_to
Type
string (YYYY-MM-DD)
Description
End date (inclusive).
Name
missing_type
Type
string
Description
The absence type identifier. See List Absence Types.
Name
target_hour_behaviour
Type
string
Description
How the absence affects target hours: substract_from_target_hours or add_to_debit_hours.

Optional Parameters

Name
affected_days
Type
decimal
Description
Number of affected working days. If omitted, it defaults to the employee's working-day count for date_from–date_to — the same value the Working Day Count endpoint returns.
Name
comment
Type
string
Description
A description or note.
Name
attachment
Type
string
Description
S3 object key of an uploaded file, obtained via the upload token flow. Join multiple keys with |.
Name
additional_fields
Type
object
Description
Custom key-value data. Keys must match the custom fields configured for your organization; unknown keys are dropped.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_from": "2024-07-15",
    "date_to": "2024-07-19",
    "affected_days": 5.0,
    "missing_type": "holiday",
    "target_hour_behaviour": "substract_from_target_hours",
    "comment": "Summer break"
  }'

PATCH/api/v2/timestamps/absence/:id/

Update an Absence

Update an existing absence.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/timestamps/absence/c1d2e3f4-a5b6-7890-cdef-123456789012/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "date_to": "2024-06-21",
    "affected_days": 10.0,
    "comment": "Extended vacation"
  }'

DELETE/api/v2/timestamps/absence/:id/

Delete an Absence

Delete an absence.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/absence/c1d2e3f4-a5b6-7890-cdef-123456789012/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/timestamps/absence/missing-types/

List Absence Types

Retrieve the available absence types configured for your organization. Each type has an ID, label, color, and a configuration object. The response is paginated.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/missing-types/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "holiday",
      "label": "Holiday",
      "color": "#4CAF50",
      "config": { "remaining_daily_hours": false }
    },
    {
      "id": "sickday",
      "label": "Sick Day",
      "color": "#F44336",
      "config": { "remaining_daily_hours": false }
    },
    {
      "id": "parental",
      "label": "Parental Leave",
      "color": "#2196F3",
      "config": { "remaining_daily_hours": false }
    }
  ]
}

GET/api/v2/timestamps/absence/target-hour-behaviours/

List Target Hour Behaviours

Retrieve the valid values for the target_hour_behaviour attribute. The response is paginated.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/target-hour-behaviours/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    { "id": "substract_from_target_hours", "label": "Von Sollstunden abziehen" },
    { "id": "add_to_debit_hours", "label": "Zu Habenstunden addieren" }
  ]
}

POST/api/v2/timestamps/absence/upload-attachment-token/

Generate an Upload Token

Generate a pre-signed S3 upload token for an absence attachment (e.g. a doctor's note). Files may be at most 15 MB, and the token is valid for 12 hours.

The attachment workflow is:

Request an upload token with this endpoint.
Upload the file to S3 with a multipart POST to the returned url, sending all returned fields plus the file itself.
Set the attachment field of the absence to the returned key when creating or updating it.
To download an attachment later, sign its key via Sign an Attachment URL.

Body Parameters

Name
employee_id
Type
string (UUID)
Description
The employee the attachment belongs to. Required.
Name
filename
Type
string
Description
Optional file name to include in the generated key.
Name
filetype
Type
string
Description
Optional MIME type (e.g. application/pdf), used to derive the file extension.
Name
filesize
Type
integer
Description
Optional file size in bytes. Requests above 15728640 bytes (15 MB) are rejected.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence/upload-attachment-token/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "doctors-note",
    "filetype": "application/pdf",
    "filesize": 240000
  }'

Response

{
  "url": "https://zeitstrom-uploads.s3.amazonaws.com/",
  "fields": {
    "key": "absence/1f2e3d4c/a1b2c3d4-e5f6-7890-abcd-ef1234567890/2024-07-15_e5f6_doctors-note.pdf",
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMDctMTZUMTA6MDA6MDBaIiwgLi4ufQ==",
    "signature": "bWq2s1WEIj+Ydj0vQ697zp+IXMU="
  }
}

POST/api/v2/timestamps/absence/sign-attachment-url/

Sign an Attachment URL

Sign an attachment key to obtain a temporary download URL. The attachment value stored on an absence is an S3 object key that cannot be downloaded directly; the pre-signed URL returned here is valid for 12 hours. If an absence has multiple attachments (pipe-separated keys), sign each key individually.

Body Parameters

Name
uri
Type
string
Description
The attachment key as stored in the absence's attachment field. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence/sign-attachment-url/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "absence/1f2e3d4c/a1b2c3d4-e5f6-7890-abcd-ef1234567890/2024-07-15_e5f6_doctors-note.pdf"
  }'

Response

{
  "presigned_url": "https://zeitstrom-uploads.s3.amazonaws.com/absence/1f2e3d4c/a1b2c3d4-e5f6-7890-abcd-ef1234567890/2024-07-15_e5f6_doctors-note.pdf?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=..."
}

GET/api/v2/timestamps/absence/working-day-count/

Working Day Count

Calculate the number of working days within a date range for specific employees. Useful for determining the affected_days value before creating an absence.

Query Parameters

Name
daterange
Type
string
Description
The date range: YYYY-MM-DD|YYYY-MM-DD. Required.
Name
employee_ids
Type
string
Description
Employee IDs, pipe-separated. Required.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/working-day-count/?daterange=2024-07-01|2024-07-31&employee_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

[
  {
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "count": 23
  }
]

GET/api/v2/timestamps/absence/working-hours/

Working Hours

Get a credit/debit summary of working hours for a specific date for employees.

Query Parameters

Name
date
Type
string (YYYY-MM-DD)
Description
The date to check. Required.
Name
employee_ids
Type
string
Description
Employee IDs, pipe-separated. Required.

The response contains one entry per employee:

Name
total_credit_hours
Type
number
Description
The employee's target working hours for the date.
Name
total_debit_hours
Type
number
Description
The hours already accounted for on the date (worked time and absences).
Name
total_days
Type
number
Description
The ratio of debit to credit hours (e.g. 0.5 if half of the day's target hours are accounted for).

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/working-hours/?date=2024-07-15&employee_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

[
  {
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_credit_hours": 8.0,
    "total_debit_hours": 4.0,
    "total_days": 0.5
  }
]

GET/api/v2/timestamps/absence/transactions/

Absence Transactions

Get absence balance transactions for employees within a date range, including starting balances and all transactions (absences taken, manual adjustments, rule-based accruals).

The response contains two objects, both keyed by employee ID and then by absence type: start_balances holds the accumulated balance from all transactions before the start of the range, and transactions lists the individual transactions within the range.

Query Parameters

Name
daterange
Type
string
Description
The date range: YYYY-MM-DD|YYYY-MM-DD. Required.
Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/transactions/?daterange=2024-01-01|2024-12-31&employee_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "start_balances": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
      "holiday": 3.0
    }
  },
  "transactions": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
      "holiday": [
        {
          "label": "Urlaub (Kontingent 2024)",
          "label_short": "Urlaub (Kontingent 2024)",
          "date": "2024-01-01",
          "amount": 30.0,
          "type": "grant-repeating-rule"
        },
        {
          "label": "Abwesenheit (10.6. - 14.6.)",
          "label_short": "10.6. - 14.6.",
          "date": "2024-06-10",
          "amount": -5.0,
          "type": "reduction-absence"
        }
      ]
    }
  }
}

GET/api/v2/timestamps/absence/ical/

iCal Export

Export absences as an iCalendar (.ics) file for integration with calendar applications. The feed includes absences from 365 days in the past to 365 days in the future.

First, generate a signed iCal URL:

Generate iCal URL

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence/ical-generate/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

The response is a plain-text URL containing a signature query parameter (?seac=...). This URL is pre-authorized by the signature — calendar applications can subscribe to it directly without sending the Authorization header.