Clockify Time Off & Holidays

Name: Clockify Time Off & Holidays
Author: vx.ai

v1.0.0 · 12 endpoints · 0 connections · shared by vx.ai

Who is off next week, and how many vacation days does Ana have left? Read Clockify time off policies and balances, list leave requests for a date range, file a request for yourself or a teammate, approve or reject pending ones, and check the workspace holiday calendar.

Connect this API to an AI agent Browse all specs

What you can do with Clockify Time Off & Holidays via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/v1/user`	getCurrentUser	Get the user the API key belongs to (id, active workspace)
GET	`/v1/workspaces/{workspaceId}/users`	listWorkspaceUsers	List or search users in a workspace
GET	`/v1/workspaces/{workspaceId}/time-off/policies`	listTimeOffPolicies	List time off policies (vacation, sick leave...)
GET	`/v1/workspaces/{workspaceId}/time-off/policies/{id}`	getTimeOffPolicy	Get one time off policy with its rules
GET	`/v1/workspaces/{workspaceId}/time-off/balance/user/{userId}`	getUserTimeOffBalances	Get a user's remaining time off per policy
GET	`/v1/workspaces/{workspaceId}/time-off/balance/policy/{policyId}`	getPolicyTimeOffBalances	Get every user's balance in one policy
POST	`/v1/workspaces/{workspaceId}/time-off/requests`	listTimeOffRequests	List time off requests filtered by status, users and dates
POST	`/v1/workspaces/{workspaceId}/time-off/policies/{policyId}/requests`	createTimeOffRequest	Request time off for yourself under a policy
POST	`/v1/workspaces/{workspaceId}/time-off/policies/{policyId}/users/{userId}/requests`	createTimeOffRequestForUser	Create a time off request for another user
PATCH	`/v1/workspaces/{workspaceId}/time-off/policies/{policyId}/requests/{requestId}`	changeTimeOffRequestStatus	Approve, reject or withdraw a time off request
GET	`/v1/workspaces/{workspaceId}/holidays`	listHolidays	List holidays set up in the workspace
GET	`/v1/workspaces/{workspaceId}/holidays/in-period`	listHolidaysInPeriod	List holidays that fall in a date range for a user

Authentication

ApiKeyAuth

API key — sent as the X-Api-Key header

Clockify personal API key, sent in the X-Api-Key header.

How to get a credential

Sign in to Clockify and open Profile settings (avatar, top right).
Scroll to API (Preferences > Advanced in newer layouts) and click Generate (or Manage API keys > Generate new).
Copy the key. It acts as you, with your role in every workspace you belong to.
Time off and holidays must be turned on for the workspace (Workspace settings > Time off; a paid plan is needed).

Permissions used

Access	Operations
Any member	getCurrentUser, listTimeOffPolicies, getTimeOffPolicy, getUserTimeOffBalances (own), listTimeOffRequests (own), createTimeOffRequest, listHolidays, listHolidaysInPeriod
Workspace admin, or manager of the user	listWorkspaceUsers, getPolicyTimeOffBalances, getUserTimeOffBalances / listTimeOffRequests for other users, createTimeOffRequestForUser, changeTimeOffRequestStatus

Common errors

401 Unauthorized: the key is missing or was regenerated; generate a new one in Profile settings.
403 Forbidden: your role cannot approve requests or see other people's balances, or time off is not enabled on the workspace.
400 Bad Request: dates in the wrong format (requests take YYYY-MM-DD, filters take 2026-10-24T00:00:00Z), a period longer than the balance allows, or an unknown policy id.
429 Too Many Requests: limit is 50 requests per second per workspace; wait and retry.

Data stored in the EU/UK/AU/US regions uses a regional host; the key itself works the same. Store the key as a VX Agents credential for this spec; never paste it into chat.

Usage guide

Setup

Credential: a Clockify personal API key (Profile settings > API) in the X-Api-Key header. It acts as you with your workspace role; approving or reading other people's leave needs an admin or manager role.
Worth pinning: workspaceId (from getCurrentUser > activeWorkspace) and, for a personal assistant, your userId.
Time off must be enabled on the workspace. Regional workspaces use a regional host (for example https://euc1.clockify.me/api).

Who is off, and approve requests

listTimeOffPolicies (status=ACTIVE) to get policy ids and names (Vacation, Sick leave...).
listTimeOffRequests with a body such as {"start": "2026-10-27T00:00:00Z", "end": "2026-11-02T23:59:59Z", "statuses": ["PENDING", "APPROVED"]}; add users (ids) or userGroups to narrow it. listWorkspaceUsers (name, email) turns names into ids.
getUserTimeOffBalances shows what a person has left per policy; getPolicyTimeOffBalances lists everyone in one policy.
To decide a pending request: changeTimeOffRequestStatus with policyId, requestId and {"status": "APPROVED"} or "REJECTED" plus an optional note. Confirm with the user first; the employee is notified.

Request time off

For yourself: createTimeOffRequest with policyId and {"timeOffPeriod": {"period": {"start": "2026-11-10", "end": "2026-11-12"}}, "note": "..."}. For a half day add "isHalfDay": true and "halfDayPeriod": "FIRST_HALF" or "SECOND_HALF".
For a teammate (admin/manager): createTimeOffRequestForUser with the same body and their userId.
Check the balance first and confirm dates and policy with the user before creating.

Holidays

listHolidays lists the workspace calendar; listHolidaysInPeriod needs assigned-to (user id), start and end and returns the holidays that apply to that person.

Good to know

Request periods use YYYY-MM-DD; list filters use UTC ISO 8601 (2026-10-24T00:00:00Z).
Ids are 24-character hex strings. Lists page with page and page-size (requests: page/pageSize in the body, max 200).
Rate limit: 50 requests per second per workspace.

Source: Clockify API reference (https://docs.clockify.me/), checked 2026-10-24.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Clockify Time Off & Holidays” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.