Absence Transactions

Absence transactions track grants and deductions on an employee's absence balance (e.g. vacation days). Grants are created by absence rules and carry positive amounts; deductions — booked absences, manually created transactions, and rule-generated reductions such as end-of-period expiry bookings — carry negative amounts.

Endpoints on this page require an API token permission: absence_transactions:view for listing, retrieving, and aggregating, absence_transactions:add for creating, absence_transactions:edit for updating, and absence_rules:delete for deleting.

The Absence Transaction Object

Name
id
Type
string (UUID)
Description
Unique identifier for the transaction.
Name
employee_id
Type
string (UUID)
Description
The employee this transaction belongs to.
Name
label
Type
string
Description
A description of the transaction.
Name
missing_type
Type
string
Description
The absence type this transaction applies to (e.g. holiday, sickday). The available types depend on your company's configuration.
Name
date
Type
string (YYYY-MM-DD)
Description
The effective date of the transaction.
Name
amount
Type
decimal
Description
The number of days. Positive amounts are grants that increase the balance; negative amounts are deductions (booked absences, manual transactions, and rule-generated reductions such as end-of-period expiry bookings). Returned as a decimal string with two decimal places, e.g. "-2.00".
Name
source
Type
string
Description
How the transaction was created: manual, absence, one-time-rule, or repeating-rule. Read-only.

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

List all Transactions

Retrieve a paginated list of absence transactions from all sources: rule-generated grants, deductions from booked absences, and manually created transactions. This endpoint uses limit/offset pagination with a default page size of 100 and a maximum of 100000.

Query Parameters

Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.
Name
daterange
Type
string
Description
Filter by date range: YYYY-MM-DD|YYYY-MM-DD. Either side may be omitted for an open-ended range: |YYYY-MM-DD or YYYY-MM-DD|.
Name
sources
Type
string
Description
Filter by source, pipe-separated: absence, manual, one-time-rule, or repeating-rule.
Name
quote_mode
Type
string
Description
Filter by absence type balance behavior: all (default) returns everything, quota returns only transactions of absence types that have at least one positive (grant) transaction, no-quota returns only transactions of absence types that have at least one negative (deduction) transaction.
Name
excludes
Type
string
Description
Pipe-separated set of exclude rules. The only supported rule is last-day:repeating-rule:lt__0, which drops negative repeating-rule transactions booked on the last day of the daterange (end-of-period expiry bookings). It only takes effect when the daterange has an end date. Unsupported rules are rejected with a validation error.
Name
limit
Type
integer
Description
Number of results per page. Defaults to 100, maximum 100000.
Name
offset
Type
integer
Description
Number of results to skip for pagination. Defaults to 0.

Request

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

Response

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "0f8b2a4c-91d3-4e5f-8a6b-7c1d2e3f4a5b",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Annual vacation entitlement 2024",
      "missing_type": "holiday",
      "date": "2024-01-01",
      "amount": "30.00",
      "source": "repeating-rule"
    },
    {
      "id": "8b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Abwesenheit (4.3. - 6.3.)",
      "missing_type": "sickday",
      "date": "2024-03-04",
      "amount": "-3.00",
      "source": "absence"
    },
    {
      "id": "3c9d1e2f-4a5b-4c6d-9e7f-8a9b0c1d2e3f",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Abwesenheit (10.6. - 14.6.)",
      "missing_type": "holiday",
      "date": "2024-06-10",
      "amount": "-5.00",
      "source": "absence"
    },
    {
      "id": "7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Correction: overbooked carryover",
      "missing_type": "holiday",
      "date": "2024-07-01",
      "amount": "-2.00",
      "source": "manual"
    }
  ]
}

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

Retrieve a Transaction

Get details of a specific absence transaction. Only manually created transactions (source: manual) can be addressed by ID; rule-generated and absence-generated entries are only available through the list endpoint.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/absence-transactions/7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "label": "Correction: overbooked carryover",
  "missing_type": "holiday",
  "date": "2024-07-01",
  "amount": "-2.00",
  "source": "manual"
}

POST/api/v2/timestamps/absence-transactions/

Create a Transaction

Manually create an absence transaction to deduct days from an employee's balance. The submitted amount must be greater than or equal to 0 and is stored as a deduction: all responses return it as a negative amount.

Name
employee_id
Type
string (UUID)
Description
The employee whose balance is reduced. Required.
Name
label
Type
string
Description
Description of the transaction. Required.
Name
missing_type
Type
string
Description
The absence type (e.g. holiday). Must be one of the absence types configured for your company. Required.
Name
date
Type
string (YYYY-MM-DD)
Description
Effective date. Required.
Name
amount
Type
decimal
Description
Number of days to deduct. Must be >= 0. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/absence-transactions/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Correction: overbooked carryover",
    "missing_type": "holiday",
    "date": "2024-07-01",
    "amount": 2.0
  }'

Response

{
  "id": "7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "label": "Correction: overbooked carryover",
  "missing_type": "holiday",
  "date": "2024-07-01",
  "amount": "-2.00",
  "source": "manual"
}

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

Update a Transaction

Update a manually created absence transaction. PATCH is also accepted, but partial payloads are rejected — all fields listed under Create a Transaction must be included with either method. As on create, the submitted amount must be >= 0 and is returned negated.

Request

curl -X PUT "https://api.zeitstrom.com/api/v2/timestamps/absence-transactions/7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Correction: overbooked carryover",
    "missing_type": "holiday",
    "date": "2024-07-01",
    "amount": 3.0
  }'

Response

{
  "id": "7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "label": "Correction: overbooked carryover",
  "missing_type": "holiday",
  "date": "2024-07-01",
  "amount": "-3.00",
  "source": "manual"
}

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

Delete a Transaction

Delete a manually created absence transaction. Note that this endpoint requires the absence_rules:delete token permission.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/absence-transactions/7e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/timestamps/absence-transactions/aggregate/

Aggregate Balances

Get net absence balances, grouped per employee and absence type. Each group sums the amounts of all matching transactions, so the endpoint accepts the same filters as the list endpoint (employee_ids, daterange, sources, quote_mode, excludes) plus the parameters below. The result is paginated.

Query Parameters

Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.
Name
balance
Type
boolean
Description
Filters the returned groups: true returns only employee/absence-type groups that contain at least one positive (grant) transaction, false returns only groups without any. Omit to return all groups.

Simulating an Absence

The aggregate endpoint can compute a what-if balance as if an additional absence had been booked, without persisting anything. The simulated absence is treated as a deduction, exactly like a regular booked absence. The first four parameters must always be provided together.

Name
simulated_employee_id
Type
string (UUID)
Description
The employee the simulated absence applies to. Must be an employee visible to the authenticated user and included in the request's employee_ids filter (if one is given).
Name
simulated_date_from
Type
string (YYYY-MM-DD)
Description
First day of the simulated absence.
Name
simulated_date_to
Type
string (YYYY-MM-DD)
Description
Last day of the simulated absence. Must be on or after simulated_date_from.
Name
simulated_missing_type
Type
string
Description
Absence type of the simulated absence. Must be one of the absence types configured for your company.
Name
simulated_affected_days
Type
decimal
Description
Optional number of days the simulated absence deducts. Defaults to the employee's working-day count within the simulated date range.

Request

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

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "missing_type": "holiday",
      "amount": 23.0,
      "has_balance": true
    },
    {
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "missing_type": "sickday",
      "amount": -3.0,
      "has_balance": false
    }
  ]
}