Skip to main content
This guide walks you through pushing employee absences — vacations, out-of-office days, sabbaticals — from an HRIS (or any system of record for time off) into Zeeg. Once a period exists in Zeeg, that user becomes unavailable for bookings on the affected days, on every scheduling page they own or share.
The endpoints in this guide live under the Availability Schedule API and require a token with schedules:write for mutations and schedules:read for reads. Mapping HRIS users to Zeeg additionally needs users:read (or admin:full).

​
Concepts

Three different objects affect a user’s availability. Pick the right one for the job: This guide focuses on time-off periods. Holiday subscriptions and weekly schedules are covered briefly at the end.

​
Time-off shape

A time-off period is all-day by default and identified by date, not datetime — there is no startTime/endTime/timeZone on the resource. Half-day flags (startHalfDay, endHalfDay) with HH:MM cutoffs let the first or last day be partial; the cutoff is interpreted in the user’s schedule timezone.

​
Prerequisites

  • A Zeeg admin or owner account with API access enabled.
  • An API token with the following scopes:
    • users:read (or admin:full) — list workspace users.
    • schedules:read — list existing time-off.
    • schedules:write — create, update, delete time-off.
  • The token owner must have edit rights on each target user’s schedules (i.e. be the user themselves, an admin/owner, or the team manager). Targets the token can’t edit are reported as failed — they don’t fail the whole request.

​
End-to-end sync flow

​
Adjacent topics

​
Public holidays

For country- or region-wide closures (Christmas, Bavarian regional holidays, US Thanksgiving), use holiday subscriptions instead of creating time-off for every user every year:
Subscriptions auto-roll forward each year — you subscribe once and the holidays keep coming. See the Holidays API reference for the full surface.

​
Recurring weekly availability

For permanent working-hour changes (someone moves to a 4-day week, or starts an hour later on Wednesdays), update the user’s availability schedule with PATCH /schedules/{uuid}. Use weeklyHours for the recurring pattern and specialHours for date-specific overrides. See PATCH /schedules/{uuid}. Don’t use specialHours to model vacations — that’s what /time-off is for. specialHours is for altering the working day on a date (e.g. “I’m only available 09:00–11:00 on this date”); time-off is for removing it.

​
Rate limits and error handling

  • The bulk POST endpoint accepts up to 10 users per request or one team of up to 200 active members. Chunk larger HRIS pulls into multiple requests.
  • For 429 Too Many Requests responses, follow the exponential backoff guidance — 1s, 2s, 4s, … capped at 60s, with a small jitter.
  • See Errors for the standard error envelope. Common time-off-specific cases:
    • 200 with status: "failed" — token can’t edit that user’s schedules. Don’t retry; surface to a human.
    • 422 No updatable fields were provided on PATCH — the request body was empty.
    • 422 This time-off period overlaps with an existing one on PATCH — fall back to POST or pick a non-overlapping range.
    • 404 Time-off period not found on PATCH/DELETE — the UUID was already deleted, or the token can’t see it. Treat DELETE 404 as success; treat PATCH 404 as a stale map entry to be cleaned up.
Run the sync on a schedule (hourly or every 15 minutes is typical), not in response to every HRIS webhook. Reconciliation is naturally idempotent and absorbs missed events; per-event delivery isn’t worth the complexity for time-off.
Last modified on May 7, 2026