Absence Applications

Absence applications represent employee requests for time off that go through an approval workflow. Applications can be created by employees or managers, then approved, declined, verified, or unverified. When an application is approved, a corresponding absence record is created automatically.

The Absence Application Object

Name
id
Type
string (UUID)
Description
Unique identifier for the application.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the application was created.
Name
modified_at
Type
string (ISO 8601)
Description
Timestamp when the application was last modified.
Name
status
Type
string
Description
Current status: new, verified, approved, or declined.
Name
absence_id
Type
string (UUID) or null
Description
The ID of the created absence (set when approved). Read-only.
Name
employee_id
Type
string (UUID)
Description
The employee who submitted the application. Read-only.
Name
date_from
Type
string (YYYY-MM-DD)
Description
Requested start date.
Name
date_to
Type
string (YYYY-MM-DD)
Description
Requested end date (inclusive).
Name
affected_days
Type
string (decimal)
Description
Number of working days requested. Returned as a decimal string with five decimal places, e.g. "5.00000".
Name
missing_type
Type
string
Description
The absence type identifier. Valid values are organization-specific and can be retrieved via the absence types endpoint.
Name
target_hour_behaviour
Type
string
Description
How the absence affects working time calculations: either substract_from_target_hours or add_to_debit_hours.
Name
comment
Type
string
Description
Employee's comment or reason.
Name
attachment
Type
string or null
Description
Storage key of an attached file (e.g. a doctor's note). Use the sign-attachment-url endpoint to obtain a temporary download URL.
Name
additional_fields
Type
object
Description
Values for custom fields configured by your organization, as a key-value object.
Name
history
Type
array
Description
History of status changes. Each entry contains event (created, verify, unverify, approved, or declined), actor (id and name of the acting user), message, time (local time), and time_utc. Always contains at least the created entry. Read-only.

GET/api/v2/timestamps/absence-applications/

List all Applications

Retrieve a paginated list of absence applications.

Query Parameters

Name
daterange
Type
string
Description
Filter by date range: YYYY-MM-DD|YYYY-MM-DD. Returns applications that overlap with the range by at least one day. Either side may be omitted for an open-ended range (e.g. |2024-06-30 or 2024-06-01|).
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
created_at__gte
Type
string
Description
Only return applications created at or after the given local timestamp (YYYY-MM-DDTHH:MM:SS).
Name
modified_at__gte
Type
string
Description
Only return applications modified at or after the given local timestamp.
Name
date_from__gte
Type
string
Description
Only return applications with a start date after the given timestamp. date_from__lte is also supported.
Name
date_to__gte
Type
string
Description
Only return applications with an end date after the given timestamp. date_to__lte is also supported.
Name
ids
Type
string
Description
Filter by application IDs, pipe-separated.
Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.
Name
employee_groups
Type
string
Description
Filter by employee group IDs, pipe-separated. Use null for ungrouped.
Name
status
Type
string
Description
Filter by status, pipe-separated: new, verified, approved, or declined (e.g. status=new|verified).
Name
missing_types
Type
string
Description
Filter by absence types, pipe-separated.
Name
q
Type
string
Description
Search by employee full name or RFID card number.
Name
has_attachment
Type
boolean
Description
Filter by presence of an attachment.
Name
order
Type
string
Description
Sort by created_at, date_from, or date_to. Prefix with - for descending order; multiple fields can be combined pipe-separated (e.g. order=-created_at|date_from). Defaults to created_at.
Name
limit
Type
integer
Description
Number of results per page. Defaults to 100, maximum 1000. Use together with offset for pagination.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/?status=new" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "d2e3f4a5-b6c7-8901-defa-234567890123",
      "created_at": "2024-06-01T09:00:00",
      "modified_at": "2024-06-01T09:00:00",
      "status": "new",
      "absence_id": null,
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "date_from": "2024-07-15",
      "date_to": "2024-07-19",
      "affected_days": "5.00000",
      "missing_type": "holiday",
      "target_hour_behaviour": "substract_from_target_hours",
      "comment": "Family vacation",
      "attachment": null,
      "additional_fields": {},
      "history": [
        {
          "event": "created",
          "actor": {
            "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
            "name": "Anna Schmidt"
          },
          "message": null,
          "time": "2024-06-01T11:00:00",
          "time_utc": "2024-06-01T09:00:00"
        }
      ]
    }
  ]
}

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

Retrieve an Application

Get details of a specific absence application.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/timestamps/absence-applications/

Create an Application

Submit a new absence application. If the absence type is configured to not require approval, the application is approved automatically on creation and the corresponding absence record is created immediately.

Name
employee_id
Type
string (UUID)
Description
The employee to create the application for. Required.
Name
date_from
Type
string (YYYY-MM-DD)
Description
Requested start date. Required.
Name
date_to
Type
string (YYYY-MM-DD)
Description
Requested end date. Required.
Name
missing_type
Type
string
Description
The absence type. Required. Valid values can be retrieved via the absence types endpoint.
Name
target_hour_behaviour
Type
string
Description
How target hours are affected: substract_from_target_hours or add_to_debit_hours. Required.
Name
affected_days
Type
decimal
Description
Number of working days. Auto-calculated from the employee's working schedule. A supplied value is only used when date_from equals date_to (e.g. for half-day requests); for multi-day applications it is ignored and always calculated by the server.
Name
attachment
Type
string
Description
Full URL of an uploaded file (the upload url joined with fields.key). Obtain an upload token via the upload-attachment-token endpoint first.
Name
comment
Type
string
Description
Reason or description.
Name
additional_fields
Type
object
Description
Values for custom fields configured by your organization, as a key-value object.

Request

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

Response

{
  "id": "e3f4a5b6-c7d8-9012-efab-345678901234",
  "created_at": "2024-06-10T14:30:00",
  "modified_at": "2024-06-10T14:30:00",
  "status": "new",
  "absence_id": null,
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "date_from": "2024-08-05",
  "date_to": "2024-08-09",
  "affected_days": "5.00000",
  "missing_type": "holiday",
  "target_hour_behaviour": "substract_from_target_hours",
  "comment": "Summer break",
  "attachment": null,
  "additional_fields": {},
  "history": [
    {
      "event": "created",
      "actor": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "name": "Anna Schmidt"
      },
      "message": null,
      "time": "2024-06-10T16:30:00",
      "time_utc": "2024-06-10T14:30:00"
    }
  ]
}

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

Update an Application

Update an existing absence application. PUT is also supported for full updates. Editable fields are date_from, date_to, affected_days, target_hour_behaviour, attachment, comment, missing_type, additional_fields, and status. Returns the updated application object. date_from and date_to must both be included in every update request, even when unchanged.

Setting status directly via this endpoint does not create an absence record or a history entry. Use the approve, decline, verify, and unverify endpoints for status changes instead.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2024-07-15",
    "date_to": "2024-07-18",
    "comment": "Family vacation (shortened by one day)"
  }'

POST/api/v2/timestamps/absence-applications/:id/grant/

Approve an Application

Approve an absence application. This creates a corresponding absence record and sends an email notification to the employee.

Name
manager_comment
Type
string
Description
Optional comment from the approving manager.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/grant/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "manager_comment": "Approved. Enjoy your vacation!"
  }'

Returns HTTP 204 No Content on success.

POST/api/v2/timestamps/absence-applications/:id/decline/

Decline an Application

Decline an absence application. An email notification is sent to the employee.

Name
manager_comment
Type
string
Description
Reason for declining.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/decline/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "manager_comment": "This period conflicts with a team deadline. Please choose different dates."
  }'

Returns HTTP 204 No Content on success.

POST/api/v2/timestamps/absence-applications/:id/verify/

Verify an Application

Mark an application as verified, indicating it has been reviewed but not yet approved. An email notification is sent to the employee; depending on the absence type configuration, an additional notification is sent to users who can approve applications.

Name
manager_comment
Type
string
Description
Optional comment from the verifying manager.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/verify/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "manager_comment": "Documents checked."
  }'

Returns HTTP 204 No Content on success.

POST/api/v2/timestamps/absence-applications/:id/unverify/

Unverify an Application

Reset a verified application back to the new status. An email notification is sent to the employee.

Name
manager_comment
Type
string
Description
Optional comment from the manager.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/unverify/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "manager_comment": "Needs another review."
  }'

Returns HTTP 204 No Content on success.

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

Delete an Application

Delete an absence application.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/d2e3f4a5-b6c7-8901-defa-234567890123/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

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

Get an Attachment Upload Token

Generate a pre-signed upload token for attaching a file (at most 15 MB) to an absence application. The response contains a pre-signed S3 url and form fields, valid for 12 hours. Upload the file as a multipart/form-data POST to url, including all fields plus the file itself. Afterwards, join url and fields.key to form the file's full URL and pass that URL as the attachment when creating or updating an application.

Name
employee_id
Type
string (UUID)
Description
The employee the attachment belongs to. Required.
Name
filename
Type
string
Description
Name of the file, used as part of the storage key.
Name
filetype
Type
string
Description
MIME type of the file (e.g. application/pdf), used to derive the file extension.
Name
filesize
Type
integer
Description
Size of the file in bytes. Validated against the 15 MB limit.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/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": 148213
  }'

Response

{
  "url": "https://s3.eu-central-1.amazonaws.com/zeitstrom-uploads",
  "fields": {
    "key": "i-f4a5b6c7-d8e9-0123-fabc-456789012345/e-a1b2c3d4-e5f6-7890-abcd-ef1234567890/absence/2024/06/10/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-10_4f2a_doctors-note.pdf",
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMDYtMTFUMDI6MzA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
    "signature": "hV0kwGx0ZQKgQnJ1zW0m9dEXAMPLE"
  }
}

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

Sign an Attachment URL

Generate a temporary, pre-signed download URL (valid for 12 hours) for an application's attachment key.

Name
uri
Type
string
Description
The attachment storage key as returned in the application's attachment field. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/sign-attachment-url/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "i-f4a5b6c7-d8e9-0123-fabc-456789012345/e-a1b2c3d4-e5f6-7890-abcd-ef1234567890/absence/2024/06/10/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-10_4f2a_doctors-note.pdf"
  }'

Response

{
  "presigned_url": "https://s3.eu-central-1.amazonaws.com/zeitstrom-uploads/i-f4a5b6c7-d8e9-0123-fabc-456789012345/e-a1b2c3d4-e5f6-7890-abcd-ef1234567890/absence/2024/06/10/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-10_4f2a_doctors-note.pdf?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=hV0kwGx0ZQKgQnJ1zW0m9dEXAMPLE&Expires=1718107800"
}

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

List Absence Types

Retrieve the valid values for the missing_type attribute. Absence types are configured per organization, so the available values vary; only types that can be selected in applications are returned.

Request

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

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "holiday",
      "label": "Urlaubstag",
      "color": "#4e79a7",
      "config": {
        "remaining_daily_hours": false
      }
    },
    {
      "id": "sickday",
      "label": "Krankheitstag",
      "color": "#59a14f",
      "config": {
        "remaining_daily_hours": true
      }
    }
  ]
}

GET/api/v2/timestamps/absence-applications/states/

List Statuses

Retrieve the valid values for the status attribute.

Request

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

Response

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    { "id": "new", "label": "Neu" },
    { "id": "verified", "label": "Geprüft" },
    { "id": "approved", "label": "Genehmigt" },
    { "id": "declined", "label": "Abgelehnt" }
  ]
}

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

List Target Hour Behaviours

Retrieve the valid values for the target_hour_behaviour attribute.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence-applications/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" }
  ]
}