VX Agents

API directory · Productivity & Project Management

Clockify Timesheet Approvals & Expenses

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

When the week closes in Clockify, submit timesheets and expenses for approval, see which approval requests are still pending, approve or send them back with a note, and review logged expenses by person and category, including the expense categories and unit prices your team bills with.

Connect this API to an AI agent Browse all specs

What you can do with Clockify Timesheet Approvals & Expenses 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.

MethodPathOperationDescription
GET /v1/user getCurrentUser Get the user the API key belongs to (id, active workspace)
GET /v1/workspaces/{workspaceId}/approval-requests listApprovalRequests List timesheet and expense approval requests by status
POST /v1/workspaces/{workspaceId}/approval-requests/resubmit-entries-for-approval resubmitEntriesForApproval Add new or rejected entries to an existing approval request
PATCH /v1/workspaces/{workspaceId}/approval-requests/{approvalRequestId} updateApprovalRequest Approve, reject or withdraw an approval request with a note
POST /v1/workspaces/{workspaceId}/approval-requests/{approvalRequestId} submitApprovalRequest Submit your timesheet or expenses for a period for approval
GET /v1/workspaces/{workspaceId}/expenses listExpenses List expenses in a workspace, optionally for one user
GET /v1/workspaces/{workspaceId}/expenses/{expenseId} getExpense Get one expense with amount, category, project and receipt info
GET /v1/workspaces/{workspaceId}/expenses/categories listExpenseCategories List expense categories (with unit and unit price)
POST /v1/workspaces/{workspaceId}/expenses/categories createExpenseCategory Add an expense category, optionally priced per unit
PUT /v1/workspaces/{workspaceId}/expenses/categories/{categoryId} updateExpenseCategory Rename an expense category or change its unit price
PATCH /v1/workspaces/{workspaceId}/expenses/categories/{categoryId}/status archiveExpenseCategory Archive or restore an expense category

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

  1. Sign in to Clockify and open Profile settings (avatar, top right).
  2. Scroll to API (Preferences > Advanced in newer layouts) and click Generate (or Manage API keys > Generate new).
  3. Copy the key. It acts as you, with your role in every workspace you belong to.
  4. Approvals and expenses must be turned on for the workspace (Workspace settings > General: Timesheet approval, Expenses; approvals need a paid plan).

Permissions used

Access Operations
Any member getCurrentUser, listApprovalRequests (own), submitApprovalRequest, resubmitEntriesForApproval, updateApprovalRequest (withdraw own submission), listExpenses (own), getExpense (own), listExpenseCategories
Workspace admin, or manager of the user listApprovalRequests / listExpenses for the team, updateApprovalRequest (approve, reject, withdraw approval)
Workspace admin createExpenseCategory, updateExpenseCategory, archiveExpenseCategory

Common errors

  • 401 Unauthorized: the key is missing or was regenerated; generate a new one in Profile settings.
  • 403 Forbidden: your role cannot approve for that user or edit categories, or approvals/expenses are off for the workspace.
  • 400 Bad Request: period does not match the workspace approval period, periodStart is not yyyy-MM-ddThh:mm:ssZ at the start of a period, or the period was already submitted.
  • 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 API key (header X-Api-Key).
  • Worth pinning: workspaceId. Call getCurrentUser once: it returns your user id and activeWorkspace.
  • Know your workspace approval period (weekly, semi-monthly or monthly): period in submissions has to match it.

Close the week: submit, review, approve

  1. Employee side: submitApprovalRequest with the path value TIMESHEET or EXPENSE (the path parameter is named approvalRequestId because it shares a URL pattern with updateApprovalRequest) and a body like {"period": "WEEKLY", "periodStart": "2026-10-19T00:00:00Z"} (the first day of the period). Confirm the period with the user first: it locks those entries for review.
  2. If entries were added after submitting, or a request came back rejected, fix them and call resubmitEntriesForApproval with the same period.
  3. Manager side: listApprovalRequests with status=PENDING (and types TIMESHEET, EXPENSE or TIMESHEET_AND_EXPENSE) shows what is waiting, sorted with sort-column START or UPDATED_AT.
  4. Decide with updateApprovalRequest: {"state": "APPROVED"}, or {"state": "REJECTED", "note": "Missing Friday hours"}. WITHDRAWN_APPROVAL reopens an approved request; WITHDRAWN_SUBMISSION lets an employee pull back their own. Always confirm the decision and note with the user before calling it.

Review expenses

  1. listExpenseCategories gives category ids, names, unit and priceInCents (for per-unit categories such as mileage).
  2. listExpenses (filter with user-id, page with page/page-size, default 50) and getExpense show amount, date, category, project, billable flag and the receipt file.
  3. Admins can add categories with createExpenseCategory (name, optional hasUnitPrice + unit + priceInCents), edit them with updateExpenseCategory or retire them with archiveExpenseCategory ({"archived": true}; old expenses keep their category).

Good to know

  • Timestamps are ISO 8601 UTC (2026-10-19T00:00:00Z); amounts are in the workspace currency, unit prices in cents.
  • The approval status filter knows PENDING, APPROVED and WITHDRAWN_APPROVAL; rejected requests drop out of it.
  • New expenses with receipts are added in the Clockify app (the API needs a multipart file upload, not included here).

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

How to use this spec

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

Related APIs

  • Notion Pages & Databases — Before stand-up, pull this week's open tasks from a Notion data source with filters and sorts, read the spec page behin…
  • Jira Issues — Lets an agent work Jira Cloud issues: search with JQL, read issues and comments, create and edit issues, assign them, c…
  • Smartsheet Sheets & Rows — For teams that run projects in Smartsheet: find a sheet, read its rows and columns, add or update rows by column id, an…
  • Asana Tasks & Projects — Lets an agent work in Asana: find workspaces, projects, sections and people, search and read tasks with their comments,…
  • Confluence Pages — Find, read and write Confluence Cloud pages: browse spaces, look up pages by title or space, read page bodies, walk the…
  • Trello Boards & Cards — Lets an agent work on Trello boards: list your boards, read lists, cards, labels and members, search cards, create and …