Hubstaff API: Build custom workflows with the API, CLI, and MCP server

The Hubstaff API gives engineers on growing global teams direct access to workforce data, with the flexibility to automate workflows and connect that data to the systems they already run.

Hubstaff is a time tracking and productivity platform used by over 140,000 users across 150 countries. With Hubstaff’s API, your developers control how data is accessed and displayed, so they can build custom workflows, plug into your existing stack, and deliver a branded, transparent experience to your clients.

It’s the largest API in its category, with one customer running it at 80,000+ employees. A CLI and MCP server sit alongside it for scripting and AI tools.

With the API, your team can:

• Automate custom workflows across your existing internal systems
• Keep workforce data in sync with tools, such as your HRIS and Hubstaff
• Enrich internal operational dashboards with the workforce data managers need
• Feed workforce data into BI tools for deeper analysis and executive reporting

This guide covers what sets the Hubstaff API apart, how access and the data model work, how the CLI and MCP server extend it to scripts and AI tools, and what your security team will want to review.

For many teams, workforce data is split across a time tracker, an HRIS, a payroll system, and an invoicing app, with numbers losing accuracy at every handoff between them. The Hubstaff API puts that data behind one set of endpoints, so your developers build against a single system of record and your leadership reports from it.

• 2× the API of the next-closest platform. Hubstaff offers twice the API coverage of the next-closest platform, measured by endpoints. More coverage means fewer requirements that force a workaround.
• Proven at scale. One customer runs more than 80,000 employees on Hubstaff’s public API. It’s the same API your team will build on, so the scale has already been tested.
• The whole loop, from clock-in to client invoice. Hubstaff is the only API that covers tracking, management, payroll, and billing. Your team builds using one API instead of stitching together a time tool, an HRIS, a payroll system, and an invoicing app.

The loop has four stages, with each one mapping to data you can read or write through the API.

The Hubstaff developer API is flexible, making it approachable for experienced software development teams and those newer to APIs.

The Hubstaff V2 API lets your dev team read and write data to build custom portals, display activities, tasks, and notes, and tailor the interface to your brand while filtering and presenting data exactly how your clients need to see it.

API access is included on the Team plan and above, with no separate subscription or add-on. Your team can build with Hubstaff API v2, Hubstaff Tasks API v1, and webhooks, all of which are covered in the Hubstaff API documentation.

Here’s a quick rundown of what your team will be working with:

• RESTful architecture: The API uses REST (Representational State Transfer) principles to create a standard and familiar interface structure that speeds up integration and reduces dev ramp-up time.
• HTTPS encryption: All API requests are secured with HTTPS using TLS encryption.
• JSON data format: The API uses JSON, a lightweight, widely adopted text-based data exchange format. This makes it simple for your team to debug, build, and iterate.
• OAuth 2.0 / OpenID Connect authentication: The API authentication system is based on the authorization system in OAuth 2.0. Industry-standard protocols keep identity verification secure and current. Hubstaff offers three access methods, and each token acts with the permissions of the member who owns it:

• • Personal Access Tokens for single-account scripts and internal tools
  • OAuth applications for integrations used by multiple users or organizations
  • Organization Access Tokens for org-owned scheduled scripts, CI jobs, and server-side automation
• Versioned endpoints: The API endpoints are versioned to make changes without breaking existing code that depends on them. Your team can confidently build with a versioned API, knowing future updates won’t break your existing workflows.

*Note: We will notify the app's owner(s) when we release newer versions and obsolete older versions. This will be a two-step process, with a grace period to deprecate and finally obsolete older versions.

Developer onboarding tips:

Your dev team will have access to the documentation and guidance they need to start building with the Hubstaff API, including:

• Detailed authentication instructions and API documentation
• Examples of typical use cases and workflows
• Instructions for how to manage their API tokens
• Guidance on optimizing the development process with RESTful principles, versioning, and rate limits
• Interactive docs in the Developer Portal for testing requests and reviewing request and response examples
• The Hubstaff CLI, the fastest way to test authentication and explore endpoints before building

Hubstaff’s API integration features connect to the systems your team already runs, and you can customize how data is delivered to you and your team.

Before diving further, here's a quick overview of the Hubstaff organization data structure, which will help you understand the correlation between key objects and entities.

The core entities

• Organizations: Organizations are the parent structure for teams. They include users, projects, and time data.
• Projects: Projects belong to organizations, can be tied to clients, and contain tasks that users track time to.
• Users: Your team members. Each user is part of an org, and you can assign them to specific projects accordingly.
• Time Entries: Time entries are the blocks of time that users track during their workday. The API can add manual time, and tracked time is read through the Activities and Daily Activities endpoints.
• Activities: Activity records come in 10-minute intervals with keyboard, mouse, overall, and tracked values. The API returns the inputs, and the activity percentage is calculated from them. Apps and URLs are available through the Tool Usages endpoints.
• Members: A member is a user’s organization membership, which carries their role and permissions. Member endpoints drive provisioning use cases.

The relationship between data and entities

• First, a “User” logs time to a “Project”, which belongs to an “Organization”.
• Time is then tracked as Activities, which attach to the user, the project, and the task.
• Each Activity carries the keyboard, mouse, overall, and tracked values for its 10-minute interval, and these inputs are what the activity percentage is calculated from.
• Timestamps in the detailed endpoints are in UTC, while Daily Activities are aggregated in the organization’s timezone. This is the most common reason API totals don’t match reports in the Hubstaff web app.

Hubstaff’s API, CLI, and MCP server let AI tools and agents query, analyze, and work with real AI-ready workforce data in real time, extending your workforce analytics into workforce intelligence.

The Hubstaff V2 API lets your development team programmatically read and write data. This allows you to build custom workflows and display Hubstaff information exactly how you need.

For example, you could build a separate, fully branded client portal with the Hubstaff API. From there, clients can log in to view filtered activities, tasks, and notes.

The API helps provide high-quality developer tools to:

• Present Hubstaff with your branding and customize the experience
• Connect data across multiple tools to uncover correlations
• Display data to your clients based on your preference

When a tool isn’t among Hubstaff’s 35+ native integrations, the API lets you build custom integrations instead.

To help your dev team draw inspiration from these custom workflows designed using the Hubstaff API, here are some use cases of syncing your internal data with the Hubstaff platform:

1. Sync time log data to internal dashboards

Use the Hubstaff API to connect workforce data to your custom internal dashboards, alongside data from existing tools your team already works with. For instance, you could combine today's tracked time with the current tracking status from Hubstaff and availability data from Slack or a calling tool. Then managers can see key information from multiple systems on a single dashboard without switching between tools.

2. Automating reports

Use the Hubstaff API to automate the delivery of weekly time and activity reports directly to your clients’ inboxes. This will inform clients on time, activity, and productivity updates across teams without manual effort.

You can build the report from the Daily Activities endpoint, which is pre-aggregated in your organization’s timezone. This lines up with the Time & Activity report, so the totals your clients receive match what your managers see in Hubstaff.

3. Attendance alerts

Utilize Hubstaff webhooks for real-time event notifications and send updates to your internal systems via HTTP callbacks. For example, you can keep an attendance or availability dashboard up to date as relevant Hubstaff events take place. This reduces the need to repeatedly perform API calls and ensures that whenever an event trigger happens, your dashboard is updated.

4. Custom workflow for time entry approval

Build a custom time entry approval workflow by pulling tracked time from the Hubstaff API’s Activities endpoints, rebuilding it into time entries, and running those entries through your custom business logic (e.g., time duration >15 mins, project validation, manual approval for weekend hours). Learn how Hubstaff lets you handle manual time approvals.

5. Payroll sync

Push approved, payroll-ready timesheets and pay rates from Hubstaff into your payroll system, so payroll runs off the same approved time. When time is edited after a sync, the Daily Activity Updates endpoint flags every record that changed since your last pull. Your integration re-sends only those records to keep payroll accurate. You can connect Hubstaff with several popular payroll integrations.

6. Provisioning and PTO sync with your HRIS

Keep members, roles, schedules, and PTO in sync with your HRIS, so a new hire, a role change, or an approved leave request automatically appears in Hubstaff. You can create and update members through the API, saving a lot of time for teams with hundreds or thousands of people. One customer runs more than 80,000 employees on Hubstaff’s public API.

7. Client billing and project budgets

Sync clients, invoices, and project budgets with your accounting system or client portal, so budgets and invoices reflect the hours tracked by your team. A client portal built on the API can show clients the same figures that appear on their invoice, and your finance team can see budget use as time is logged.

Before an integration goes live, your IT or security team will want to know how it authenticates, what it can reach, and what compliance standards the vendor meets. Here’s what you need to know about the Hubstaff API, CLI, and MCP server:

• The API uses OAuth 2.0 and OpenID Connect. Hubstaff doesn’t issue API keys or support Basic Authentication.
• Every token acts with the role and permissions of the member who owns it, meaning an integration can’t reach data its owner can’t.
• Organization Access Tokens can be set to expire after 30, 60, or 90 days, which suits automation that runs on a schedule.
• Every API request is sent over HTTPS with TLS encryption.
• MCP server access is limited to owners and managers. Passwords are never shared with the AI client.
• Hubstaff meets GDPR, SOC 2 Type II, HIPAA, LGPD, and CCPA standards.

You can visit our Trust center for current compliance documentation your team can review before approving access.

The Hubstaff API is a foundation for building smarter, more connected systems that put your brand and dev team in complete control. The API gives you the autonomy and precision to tailor workflows to your needs. It offers 2× the API of the next-closest platform, is proven at scale, and is the only API that runs from clock-in to client invoice, with a CLI and MCP server for scripts and AI tools.

Use it for optimizing time tracking, syncing project data, automating reports, or delivering a branded client experience. With rich documentation, getting started is simple. Explore the Hubstaff Developer Portal and start building with the API today.