Time Tracking API from Hubstaff

Why Use the Hubstaff API?

The ability to read and write your data from Hubstaff will allow you to create your own custom solutions for displaying the data. For example, if you want to customize the Hubstaff platform as a portal for your clients to log in and view activities, tasks, notes, and more. This can be achieved by inviting clients to Hubstaff, but the API allows you to present Hubstaff with your own branding and customize the experience. With the various filters available the data can be arranged and displayed how you want to show it to your clients.

Hubstaff Time Tracking API

The Hubstaff Time Tracking API allows you to read and write time and activity data from Hubstaff. For the following:

• Users
• Activities
• Reports
• Tasks
• Integrations
• Location
• Job sites
• All-time data

Authentication

Our APIs are using OpenID Connect for authentication.

We use this because it provides a secure method of authentication and builds on the authorization system in OAuth 2.0.

We also provide a personal access token system as well. This better targets server-side script applications that cannot easily utilize the interactive login we enforce by OpenID Connect + OAuth 2.0.

The personal access token system is slightly different from other applications in that the token you receive is a refresh token that has a long expiration time (90 days). Read more on how to obtain an access token from a personal access token refresh token.

This can be done by going to https://developer.hubstaff.com/apps and clicking New.

API Reference V2 Endpoints

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.

You can see the list of API V2 endpoints that you can use here https://developer.hubstaff.com/docs/hubstaff_v2

Important Notes

• The Hubstaff time tracking API has now read and write functions.
• 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 JSON formats. The data you request is returned in the same format you requested it in.
• There are rate limits in place to ensure the availability of the API and protect against possible abuse. Authenticated users are allowed 1000 requests 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.
• 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.
• 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 api@hubstaff.com.

Frequently Asked Questions

We are planning to get an access token using client id and secret to use the API endpoint. Is this possible?

We support two methods of obtaining access tokens.

1. Using the OAuth authorization code flow (https://auth0.com/docs/flows/concepts/auth-code).

2. Using a personal access refresh token – this is documented on our authentication page (https://developer.hubstaff.com/authentication#pat).

I tried to authenticate using OpenID, but what do I do if I get the “Invalid Authentication Request” error?

In your URL you specify http://localhost:3000/hubstaff/oauth as the callback URL, however, in your client app you have it configured as http://localhost:3000/hubstaff/oauth/callback.
This is the reason for the error. You must have the URL exactly in order for it to pass validation. Note that you may have multiple redirect URLs defined as well.

I don’t find any endpoint to get “time is logged to a task” in Hubstaff data. Where is that?

You can use organization activities or organization activities/daily endpoint. You can then simply filter by task_id to see activities for a single, or set of tasks.

https://developer.hubstaff.com/docs/hubstaff_v2#!/activities/getV2OrganizationsOrganizationIdActivities

https://developer.hubstaff.com/docs/hubstaff_v2#!/activities/getV2OrganizationsOrganizationIdActivitiesDaily

Always prefer the daily activities endpoint as it is much faster to get data since it is pre-aggregated to the organization day.

I’m trying to use your API but keep getting an error when I try to connect to the demo app I’ve just created.

{“error”: “access_denied”,”error_description”: “nonce required”}

I’m using the Auth0 service and everything looks properly configured. What is “nonce”?

We are using OpenID Connect which requires a nonce for the authorization request (https://developer.hubstaff.com/authentication#authorizing).
So, make sure your app is configured to utilize OpenID Connect so that it sends a nonce.

We’re trying to create a reporting application based on Hubstaff data, but we need to do this in “schedule run” like using “cron job.” Is there a way to call the API using the client id and client secret to generate a token to use some endpoint?

We do not support client authentication (as there is no user in that mode). However, we have personal access tokens that fit perfectly into that use case.

Our PATs are slightly different from other systems in that they do expire. So, when you go to the PAT page on the developer site (https://developer.hubstaff.com/personal_access_tokens) you are creating a personal refresh token. Then you use that token to start the process of getting an access token the same way as standard OAuth 2 does. You make a refresh_token request to our token endpoint (as described here https://developer.hubstaff.com/authentication#pat).

How can we export timesheets to CSV with the API (Time & activities report > Export)?

If you need to know the exact start and stops then you have raw activities endpoint for now and build up the time sessions yourself.

E.g., given 3 activities
start 10:05:00Z, tracked = 300, project_id: 5, task_id: 23
start: 10:10:00Z, tracked = 540, project_id: 5, task_id: 23
start: 10:21:00Z, tracked = 350, project_id: 5, task_id: 23

Which means, that you have a time session that starts at 10:05:00Z and lasts for 840 seconds (up until 10:19:00Z). And then a second time session that starts at 10:21:00 and lasts until 10:26:50Z.

How can I get a list of all of our organization’s users with user ID’s from the API?

Currently, the way to get a list of all the user IDs is via the organization/#/members endpoint. Then you can hit the /users/# endpoint and cache those results.