Getting started with the HourSquare API

What the API is

Everything public lives under https://api.hoursquare.com/api/public/v1. There is one host for the whole product, so the address you integrate against does not change as HourSquare grows. Requests and responses are JSON; errors come back as application/problem+json with a stable error string, described in the reliability guide.

Keys belong to the company, not to the person who created them. If that person leaves, the key keeps working until someone revokes it, and everything a key does is recorded as done by that key.

Who can create a key

An administrator with the Manage API keys permission opens Hub › Settings › API & integrations and clicks Create. A key gets a name, one or more scopes (what it may do), an optional expiry date and, optionally, a list of allowed IP ranges.

A key can only be granted scopes its creator is allowed to grant. Machine scopes such as attendance.record are always available; human scopes such as employees.read require the creator to hold the matching permission, or to be a super admin.

The two strings you get

Creating a key shows two values, once:

• Client ID — hsq_k7Qm3xZp. Not secret. It is also printed in the key list, so you can always find it again.
• Client secret — the full key, hsq_k7Qm3xZp_…. Shown a single time. HourSquare stores only a hash of it; if you lose it, rotate the key and store the new one.

Get a token

The API uses the OAuth 2.0 client-credentials grant. Exchange the key for a short-lived access token at the token endpoint, then send that token as a Bearer header on every call. The two forms below are equivalent; $HSQ_KEY holds the client secret.

curl -s -X POST https://api.hoursquare.com/api/public/v1/oauth/token \
  -u "hsq_k7Qm3xZp:$HSQ_KEY" \
  -d grant_type=client_credentials

curl -s -X POST https://api.hoursquare.com/api/public/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id=hsq_k7Qm3xZp \
  --data-urlencode "client_secret=$HSQ_KEY"

{
  "access_token": "eyJhbGciOiJIUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 900
}

A token lives for 15 minutes (expires_in is seconds). Cache it in memory and reuse it until it expires or a call answers 401; then request a new one. There is no refresh token: the key is what you refresh with. The token endpoint accepts 60 requests a minute per key, which is plenty once you cache.

The token endpoint answers 400 invalid_request or unsupported_grant_type for a malformed call, and 401 invalid_client for a wrong, expired or revoked key.

Your first request

GET /api/public/v1/me answers for any valid token and tells you what the token can do, when it expires and what your quota is.

curl -s https://api.hoursquare.com/api/public/v1/me \
  -H "Authorization: Bearer $TOKEN"

{
  "principal": "api_key",
  "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "publicId": "hsq_k7Qm3xZp",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "scopes": [
    {
      "id": "attendance.record",
      "permission": 86,
      "label": "Record clock events and completed shifts; set employee external ids"
    }
  ],
  "tokenExpiresAt": "2026-09-15T10:15:00+00:00",
  "rateLimit": { "requestsPerMinute": 300, "tokenRequestsPerMinute": 60 },
  "dryRunHeader": "X-HourSquare-Dry-Run"
}

Every response also carries RateLimit headers, so you can watch your remaining quota without a separate call.

Explore the reference

The interactive reference at api.hoursquare.com/docs lists every endpoint with its request and response schemas and lets you call the API from the page. Paste a Client ID and secret into its Connect panel (the token stays in memory, never in storage) and try a request. Write operations there send X-HourSquare-Dry-Run: true by default, so nothing is written until you switch it off.

Next: authentication and scopes, then the time-clock walkthrough.