Hubstaff provides an API that can be used to retrieve most of its resources and reports. The API will continue to evolve as more endpoints and capabilities are added.

We are committed to providing quality developer tools. Send any issues or suggestions to support@hubstaff.com.

Common HTTP client tools such as cURL can be used to test the API. We have also provided a convenient method to test directly within our API documentation.

Our documentation is interactive so that you can get started quickly by testing directly within your web browser.

1. Pick an API reference to view
2. Click the Authorize button to authenticate for that API
3. Make your first API request (start with /users/me)

We have a simple demo showing how to use a personal access token on our Github account.

• Node.js PAT demo
• PHP PAT demo
• Postman collection

RESTful

The API uses REST principles to create a standard and familiar interface. If you are new to the concept of REST here is an explanation.

HTTPS

A secure HTTPS connection (SSL) is required in order to make requests to the server. Requests made over HTTP (port 80) will be redirected to HTTPS (port 443).

JSON

The Hubstaff API supports only JSON.

Open ID Connect / OAuth based

Our Authentication is based on the industry standard Open ID Connect which utilizes OAuth 2.0.

Read more on the authentication page.

Versioned API

The API endpoints are versioned so that changes can be made to them without breaking existing code that depends on them. We will notify the app's owner(s) when we release newer versions and obsolete older versions.

There will be a two step process with a grace period to first deprecate and finally obsolete older versions.

Rate limit

In order to protect against excessive use of the API and ensure availability to all consumers the API is rate limited.

We have an initial rate limit of 1000 requests per hour per application. Contact us if you need a higher limit.

When you hit a rate limit you will receive a 429 HTTP status code response. There will also be a Retry-After header provided which will specify the number of seconds until the limit resets.

Result set limits

As a best practice the APIs have limits on how much data it will return in a response. The limits are noted on each endpoint.

Paginated responses

Any listing endpoint is paginated by default. Records are always sorted by creation order. In the response there will be a pagination key that will describe details on fetching the next page.

{
  organizations: [
    {
      id: 1,
      name: 'My organization',
    },
    ...
  ],
  pagination: {
    next_page_start_id: 98
  }
}

With this response the next request should be made with the same parameters as the first, but with a page_start_id of 98.

The default page size is 100. However, this can be overridden as needed. The endpoint may apply restrictions to the page size as appropriate.