Absence Rules

Absence rules grant absence entitlements to employees. A manually created rule is a one-time grant: the full amount becomes available on available_from and is removed again on expires_at. Recurring annual or monthly entitlements are configured through employee settings and appear here as read-only rules with source: "setting".

These endpoints require an API token with the absence_rules:view, absence_rules:add, absence_rules:edit, or absence_rules:delete permission, depending on the operation.

The Absence Rule Object

Name
id
Type
string (UUID)
Description
Unique identifier for the rule. Only manually created rules have a persistent id that can be used in the retrieve, update, and delete endpoints; ids of setting-generated rules are derived values.
Name
employee_id
Type
string (UUID)
Description
The employee this rule applies to.
Name
label
Type
string
Description
Description of the rule.
Name
missing_type
Type
string
Description
The absence type this rule grants entitlements for. Must be one of the absence types configured for your institution.
Name
amount
Type
string (decimal)
Description
Total number of days granted by the rule. Returned as a decimal string with two decimal places, e.g. "30.00". Must be >= 0.
Name
priority
Type
integer
Description
Evaluation priority. Lower values are evaluated first. Must be >= 0.
Name
available_from
Type
string (YYYY-MM-DD)
Description
Date from which the granted days are available. Must be on or before expires_at.
Name
expires_at
Type
string (YYYY-MM-DD)
Description
Date on which the grant expires. Always set; setting-generated rules that never expire are returned with the date 9999-12-31.
Name
source
Type
string
Description
How the rule was created: manual or setting. Read-only. Rules with source setting are generated from employee settings and cannot be created, updated, or deleted through this API.

GET/api/v2/timestamps/absence-rules/

List all Rules

Retrieve a paginated list of absence rules, including both manually created rules and rules generated from employee settings.

Query Parameters

Name
daterange
Type
string
Description
Filter by date range: YYYY-MM-DD|YYYY-MM-DD. Either side can be left empty for an open-ended range (|YYYY-MM-DD or YYYY-MM-DD|). The start date only returns rules with available_from on or after it; the end date bounds how far into the future setting-generated rules are expanded.
Name
sources
Type
string
Description
Filter by source. Accepts one or more pipe-separated values, e.g. sources=manual or sources=manual|setting.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence-rules/?daterange=2024-01-01|2024-12-31" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "c4d5e6f7-a8b9-4012-8cde-f23456789012",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Bonus vacation days",
      "missing_type": "holiday",
      "amount": "5.00",
      "priority": 0,
      "available_from": "2024-01-01",
      "expires_at": "2024-12-31",
      "source": "manual"
    },
    {
      "id": "7f3a9b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Urlaubstage (Kontingent 2024)",
      "missing_type": "holiday",
      "amount": "30.00",
      "priority": 2,
      "available_from": "2024-01-01",
      "expires_at": "9999-12-31",
      "source": "setting"
    }
  ]
}

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

Retrieve a Rule

Get details of a specific absence rule. Only manually created rules (source: "manual") can be retrieved by id; setting-generated rules are not addressable and return 404 Not Found.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence-rules/c4d5e6f7-a8b9-4012-8cde-f23456789012/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "c4d5e6f7-a8b9-4012-8cde-f23456789012",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "label": "Bonus vacation days",
  "missing_type": "holiday",
  "amount": "5.00",
  "priority": 0,
  "available_from": "2024-01-01",
  "expires_at": "2024-12-31",
  "source": "manual"
}

POST/api/v2/timestamps/absence-rules/

Create a Rule

Create a new absence rule for an employee. The rule grants the full amount once, available from available_from until expires_at.

Name
employee_id
Type
string (UUID)
Description
The employee. Required.
Name
label
Type
string
Description
Description of the rule. Required.
Name
missing_type
Type
string
Description
The absence type. Required. Must be one of the absence types configured for your institution.
Name
amount
Type
string (decimal)
Description
Total number of days to grant. Required. Must be >= 0.
Name
priority
Type
integer
Description
Evaluation priority (lower = higher priority). Required. Must be >= 0.
Name
available_from
Type
string (YYYY-MM-DD)
Description
Date from which the granted days are available. Required. Must be on or before expires_at.
Name
expires_at
Type
string (YYYY-MM-DD)
Description
Expiration date. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-rules/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Bonus vacation days",
    "missing_type": "holiday",
    "amount": "5.00",
    "priority": 0,
    "available_from": "2024-01-01",
    "expires_at": "2024-12-31"
  }'

PUT/api/v2/timestamps/absence-rules/:id/

Update a Rule

Update an existing absence rule. Only manually created rules (source: "manual") can be updated.

PATCH requests are accepted on this endpoint but behave like PUT: the full payload with all required fields must be sent. Partial updates are not supported.

Request

curl -X PUT "https://api.zeitstrom.com/api/v2/timestamps/absence-rules/c4d5e6f7-a8b9-4012-8cde-f23456789012/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Bonus vacation days (reduced)",
    "missing_type": "holiday",
    "amount": "3.00",
    "priority": 0,
    "available_from": "2024-01-01",
    "expires_at": "2024-12-31"
  }'

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

Delete a Rule

Delete an absence rule. Only manually created rules (source: "manual") can be deleted. Absence balances are recomputed from the remaining rules, so deleting a rule removes the entitlement it granted from future balance calculations.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/absence-rules/c4d5e6f7-a8b9-4012-8cde-f23456789012/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"