Clockodo for Home Assistant

A custom integration that pulls your Clockodo absences into Home Assistant so you can see (and automate on) when you're on holiday.

It adds one device with four entities:

Entity	Type	What it tells you
On holiday	binary_sensor	on when today falls inside an approved holiday period. Attributes: since, until, days.
Next holiday	sensor (date)	Start date of your next upcoming holiday. Attributes: until, days, days_until, status.
Remaining vacation days	sensor (number)	entitlement + carry-over − days taken for the current year. Attributes: entitlement, carryover, taken, planned.
Holidays this year	sensor (count)	Number of holiday periods this year. Attribute holidays is the full list (from/to/days/status) for a calendar/markdown card.

"Holiday" means Clockodo absence type 1 – Regular holiday (Urlaub). Sick days, special leave, etc. are ignored. By default only approved absences count; you can opt to include requested-but-not-yet-approved ones in the options.

How it works

The integration talks to the official Clockodo REST API with simple, non-expiring API-key headers (X-ClockodoApiUser / X-ClockodoApiKey), which is what makes it a clean fit for Home Assistant — no OAuth, no token refresh. It polls once an hour by default. Endpoints used (read-only):

• GET /v4/users/me – identifies your account (so you never have to look up your user ID)
• GET /v4/absences – your absences for this year and next
• GET /v2/holidaysQuota – your yearly holiday entitlement
• GET /v3/holidaysCarry – days carried over from last year

Installation

Option A — HACS (custom repository)

1. HACS → ⋮ → Custom repositories.
2. Add this repo's URL, category Integration.
3. Install Clockodo, then restart Home Assistant.

Option B — Manual

Copy the custom_components/clockodo folder into your Home Assistant config directory so you end up with config/custom_components/clockodo/…, then restart Home Assistant.

Setup

1. In Clockodo, open your profile → Personal data → API and copy your API key. (Your Clockodo login e-mail is the "API user".)
2. In Home Assistant: Settings → Devices & services → Add integration → Clockodo.
3. Enter your login e-mail and API key. The optional "technical contact e-mail" is only sent to Clockodo in the required application-identification header; it defaults to your login e-mail.

Options

After setup, click Configure on the integration to change:

• Update interval (seconds, minimum 300) — default 3600.
• Also count not-yet-approved (requested) holidays — default off.

Example automation

Don't fire the weekday work alarm while you're on holiday:

automation:
  - alias: "Work alarm (skip holidays)"
    trigger:
      - platform: time
        at: "06:30:00"
    condition:
      - condition: time
        weekday: [mon, tue, wed, thu, fri]
      - condition: state
        entity_id: binary_sensor.clockodo_on_holiday
        state: "off"
    action:
      - service: script.turn_on
        target:
          entity_id: script.morning_routine

Example dashboard card

type: entities
title: Holidays
entities:
  - entity: binary_sensor.clockodo_on_holiday
  - entity: sensor.clockodo_next_holiday
    secondary_info: last-changed
  - entity: sensor.clockodo_remaining_vacation_days
  - entity: sensor.clockodo_holidays_this_year

Days-until the next holiday is available as an attribute for a template/markdown card:

type: markdown
content: >
  {% set n = state_attr('sensor.clockodo_next_holiday','days_until') %}
  {% if n is not none %}🏖️ Next holiday in **{{ n }} days**
  ({{ states('sensor.clockodo_next_holiday') }}).{% else %}No holiday booked.{% endif %}

Notes & limitations

• Requires Home Assistant 2024.6 or newer (uses entry.runtime_data).
• The Remaining vacation days sensor needs the Clockodo absence module and the right to read your holiday quota. If the quota can't be read, that one sensor stays unavailable; the others keep working.
• Remaining days follow Clockodo's own logic: entitlement + carry-over − approved days. Requested (not yet approved) days are reported separately as the planned attribute and are not subtracted.
• Absence enums are documented by the Clockodo SDK (peerigon/clockodo): type 1 = Regular holiday; status 0 reported, 1 approved, 2 declined, 3 approval cancelled, 4 request cancelled.

---

Not affiliated with or endorsed by Clockodo GmbH.