Hubstaff Time Tracking API
The Hubstaff Time Tracking API allows you to retrieve time and activity data from Hubstaff. You can retrieve:
- All time data
Why Use the Hubstaff API?
The ability to retrieve your data from Hubstaff will allow you to create your own custom solutions for displaying the data. For example, if you wanted to white-label the Hubstaff platform you could build a portal for your clients to log in and view activities, tasks, notes, and more. This would save you from needing to invite clients to Hubstaff.
With the various filters available, the data can be arranged and displayed how you want to show it to your clients.
Getting Started – Creating Your First App
First, visit My Apps in the Hubstaff time tracking API documentation. Next, click the “Create app” button (you will need to be signed into your account and also be the owner of an organization in order to see this):
Give the app a name and click “Save”. You will now see the app appear along with an App token and options to generate a new token, update the app, or delete it:
Hubstaff’s time tracking API is designed to use token-based authentication. Every request needs to have both an App token (which you generate at My Apps) and an Auth token (this is what authenticates the user). To get your auth token, head over to the API Reference. There you will see documentation of all the different ways to retrieve data. For example, if you’d like to test obtaining an auth token for a user, you can click the following section to reveal the instructions:
You can choose the response content type (JSON or XML), then enter in the required parameters. For obtaining a user’s auth token, you would enter in your App token, Hubstaff account email, and Hubstaff account password. Then click the “Try it out!” button to see the response.
Note: If your request doesn’t have both a valid App and Auth token, the response will be “401 Unauthorized Error”
Once you have your auth token you will be able to make API requests to retrieve users, projects, activities, notes, tasks, weekly reports, and custom reports.
You can make requests with HTTP client tools (cURL is one popular option). A sample cURL request would look like the following:
This would return all the organizations that the user whose auth token is supplied belongs to.
Hubstaff’s interactive API Reference details all the requests you can make, along with the different parameters and options. It even allows you to test them directly inside the browser.
- The Hubstaff time tracking API is currently read-only so it can only be used to retrieve data. We do plan to continually evaluate user needs and may offer write privileges in the future.
- Make sure you are using an auth token of a user that has a manager or an owner role at the organization level if you want to access all the data for an organization.
- Secure HTTPS connections are required for making requests. HTTP requests are redirected to HTTPS.
- Hubstaff’s API supports XML and JSON formats. The data you request is returned in the same format you requested it in.
- There are rate limits in place to ensure availability of the API and protect against possible abuse. Authenticated users are allowed 1000 requests every hour (per app). For authentication requests, just 10 are permitted every hour (per app). There are also result set limits which you can see detailed on each endpoint’s section in the API Reference. Offset parameters are used in some cases to paginate through result sets.
- Hubstaff’s API uses RESTful principles.
- The API endpoints seen in the API Reference are versioned. This is done so updates and changes can be made without breaking any code. As new versions are released we will make sure to keep app developers informed.
- An authentication error means the end-user typed the headers incorrectly or aren’t specifying them. Always make sure they are as follows: Auth-Token and App-Token (no _ or lowercase ‘a’ and ‘t’).
- There is a 30 second limit imposed by our current hosting solution. So if a request takes longer than 30 seconds you will receive a blank response. In those cases, retrying, limiting the date range, adding organization filters, or user filters may be required.
- You may get blacklisted automatically if you don’t send the app token header correctly a number of times. To prevent yourself from being blacklisted, you’ll want to make sure that you’re sending the app token header with every request, and you’ll want to make sure you’re using the correct app token. The blacklist will automatically be removed after 24 hours, so you’ll be able to use the API again after that time.
- The Hubstaff time tracking API is constantly being developed. More capabilities and endpoints will continue to be added over time and suggestions or problems are always welcome – just send them to firstname.lastname@example.org.
- We have an unofficial PHP library that interacts with our public API. Feel free to check out the open source package at https://packagist.org/packages/techsemicolon/hubstaff