Get a chronological list of who is off between two dates.

The single best endpoint for "who is off on/around a given day" — it merges bookings, non-working days, public holidays and (optionally) other events without needing multiple queries.

Args: start: Start date, ISO format YYYY-MM-DD. end: End date, ISO format YYYY-MM-DD. Max 31 days after start. query_type: What to include. AllAbsences (bookings, public holidays and non-working days), Bookings, PublicHolidays or AllEvents (also birthdays, work anniversaries and locked dates).

Rate limited to 1 request per second; limited to a 31-day range.

List allowances, TOIL and carry-forward for all users.

Args: year: Restrict to a single year. Omit for all years.

Get allowances, TOIL and carry-forward for one user.

Args: user_id: The user to query. year: Restrict to a single year. Omit for all years.

Set a user's annual allowance for a year.

Args: user_id: The user to update. year: The year to update. amount: The new allowance (0–8784).

Set a user's carry-forward amount for a year (0–5000).

Add a TOIL (time off in lieu) entry for a user in a year.

Args: user_id: The user to add TOIL for. year: The year the TOIL applies to. amount: TOIL amount (-5000 to 5000). description: Optional description (max 1000 chars).

Returns the ID of the new TOIL entry.

Update an existing TOIL entry (-5000 to 5000).

Delete a user's TOIL entry.

List all departments in the organisation.

Get a single department by ID.

Create a new department.

Args: name: The department name. manager_id: User ID of the department manager. max_off: Max number of users off at once (0 = no limit).

Edit a department. Only the fields you supply are changed.

Args: department_id: The department to edit. name: New department name. manager_id: User ID of the department manager. max_off: Max users off at once (0 disables the limit; range 0–20).

Delete a department. It must be empty (reassign any users first).

Query leave bookings ("holidays") for the organisation.

All filters are optional. Results are paginated at 100 per page — use page_number and read totalRecords/nextPageLink in the response.

Args: start: Include holidays on or after this date-time (ISO 8601). end: Include holidays before and including this date-time (ISO 8601). status: Filter by status. Defaults to pending + approved if omitted. user_ids: Comma-separated user IDs to include (e.g. "12,34"). exclusion_user_ids: Comma-separated user IDs to exclude. department_id: Only holidays for this department. leave_type_id: Only holidays of this leave type. approver_id: Only holidays approved by this user. my_team_only: Restrict to the team of this user ID. my_favourites_only: Restrict to the favourite users of this user ID. department_managers_only: Only holidays for department managers. non_archived_users_only: Exclude archived users. transaction_year: Filter to this transaction year. page_number: Page to fetch (defaults to 1).

Get a single holiday (leave booking) by its ID.

Submit a leave request (book time off).

Args: from_date: Start date YYYY-MM-DD (no time component). to_date: End date YYYY-MM-DD (no time component). leave_type_id: The leave type to book (see list_leave_types). book_for: User, Department or Everyone. user_or_department_id: ID of the user/department to book for (with book_for). Omit to book for yourself. from_time: Part of the start day: "AM", "PM", or minutes since midnight for an hourly booking. to_time: Part of the end day: "AM", "PM", or minutes since midnight for an hourly booking. reason: Optional reason for the request. suppress_emails: Admins only — suppress notification emails. book_as_requestee: Admins only — book as if the requestee made it so the normal approval flow runs (default is auto-approved by the admin). override: Admins only — bypass the department max-off limit. override_locked_days: Admins only — book over locked dates. override_accrued_allowance: Admins only — bypass accrued-allowance check. attachment_id: Attach a previously uploaded attachment by ID.

Approve, decline or cancel a holiday.

Args: holiday_id: The holiday ID (or a holiday token). action: Approve, Decline, Delete (cancel this booking) or DeleteGroup (cancel the whole group booking). reason: Optional reason, typically used when declining/cancelling. suppress_emails: Suppress notification emails when actioning.

Raises a webhook event if webhooks are configured.

List leave types for the organisation.

Args: include_inactive: Also return inactive (deleted) leave types.

Get a single leave type by ID.

List the valid colour hex codes for leave types.

List the valid icon names for leave types (empty string = no icon).

Create a new leave type (admins only).

Args: name: Name of the leave type (1–50 chars). deducted: Whether it deducts from the user's allowance. requires_approval: Whether bookings need approval. include_max_off: Whether it counts toward max-absent limits. is_private: Whether the leave type is private. color: A hex colour (see list_leave_type_colors). icon: An icon name (see list_leave_type_icons). calendar_visibility: Busy, Available or OutOfOffice. limit_hours: Optional limit in hours. limit_days: Optional limit in days.

Returns the ID of the new leave type.

Update an existing leave type (admins only). name is required.

Delete (deactivate) a leave type. Cannot delete the last active one.

List all locked dates (periods where booking time off is blocked).

Add a locked date period.

Args: from_date: Start of the locked period (ISO 8601 date-time). to_date: End of the locked period (ISO 8601 date-time). reason: Reason for the lock (1–2000 chars). record_type: Scope of the lock: Organisation, Department or User. Higher-level locks supersede lower-level ones. record_id: The organisation, department or user ID the lock targets.

Delete a locked date by ID (admins/authorised managers only).

List public holidays for the organisation.

Args: country_code: Filter to a country code. year: Filter to a year. user_id: Filter to a user's public holidays. bank_holiday_set_id: Filter to a bank holiday set. use_org_leave_year: Use the user's leave year instead of calendar year.

Get a single public holiday by ID.

List all countries available for public holidays.

List users in the organisation, optionally filtered by department.

Args: department_id: Only users in this department. include_archived_users: Include archived users in the results. only_show_archived_users: If archived users are included, show ONLY them.

Get a user by ID, including work schedule and allowance breakdown.

Get a user with contact-tab details (address, phone, emergency contact).

Requires a Timetastic Pro account.

Add a new user to Timetastic.

Args: first_name: The user's first name. last_name: The user's last name. department_id: The department to place the user in. allowance: Annual leave allowance in days (0–366). email_address: The user's email address. start_date: Start date, ISO 8601 (e.g. 2022-02-04T00:00:00). leave_year_start: Month the leave year starts (1=Jan … 12=Dec). send_welcome_email: Email the user to set a password and get started.

Edit a user. Only the fields you supply are changed (partial update).

Args: user_id: The ID of the user to edit. email_address: New email. Pass "" to clear an existing address. approver_id: The user's approver; set to 0 to default to dept manager. public_holiday_set_id: Public holiday set (needs has_public_holidays). has_public_holidays: Enable public holidays for this user. (Other args map directly to the corresponding user fields.)

Archive a user. They are logged out immediately and cannot log in.

Args: user_id: The ID of the user to archive. archive_date: The date the user left (UTC, must be in the past), ISO 8601. Shown on their archived profile and in reports.

Restore an archived user so they can use Timetastic again.

Assign a set of public holidays to a user (enabling them if needed).

Args: user_id: The user's ID. country_code: ISO 3166-1 alpha-2 country code (e.g. "ES" for Spain). region_code: Full region code (e.g. "GB-SCT" for Scotland, "ES-AN" for Andalucía).

If the chosen country/region is already used by your organisation, that (possibly customised) set is used; otherwise the standard set is assigned.

List recent webhook events (up to 30 days of history are retained).

Args: days_history: How many days of history to return (defaults to 1).