API Getting Started, Authentication & Responses

API documentation hub

Start here to authenticate, make your first request, interpret responses, and retrieve server metadata.

On this page

1. 1. Quick start
2. 2. Authentication
3. 3. Response conventions
4. 5. Health & authentication
5. 6. Server metadata

1. Quick start

export API_BASE="https://secure.timesheets.com/api/public/v1"
export API_KEY="YOUR_API_KEY"
export TOKEN="YOUR_JWT_TOKEN"

# No auth
curl -s "$API_BASE/health-check"

# Authenticate (primary admin of an active/trial account)
curl -s -X POST "$API_BASE/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@example.com","password":"secret"}'

# Authenticated call (most endpoints)
curl -s "$API_BASE/users?Status=USER_STATUS_ACTIVE&MaxRows=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

Header	When required
Authorization: Bearer <JWT>	Most endpoints
apikey	Most mutating / standard authenticated endpoints (pairs with JWT)
Content-Type: application/json	Requests with a JSON body
Authorization: <apikey> (no Bearer)	Clock shift endpoints only

---

---

2. Authentication

1. Call POST /auth/token with username and password (no prior token).
2. Receive apikey, token, and optional auth_headers.
3. Send both apikey and Authorization: Bearer <token> on subsequent requests (except clock endpoints — apikey only).

Only primary administrators of active or trial accounts can obtain API credentials. Keys are rate-limited (default 5 requests / 60 seconds unless whitelisted). Exceeding the limit returns HTTP 420.

curl -s -X POST "$API_BASE/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@example.com","password":"secret"}'

{
  "apikey": "abc123...",
  "token": "eyJhbGciOi...",
  "auth_headers": {
    "apikey": "abc123...",
    "Authorization": "Bearer eyJhbGciOi..."
  }
}

List active keys for the current user:

curl -s "$API_BASE/auth/token" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

---

---

3. Response conventions

Most endpoints return HTTP 200 even when validation or business rules fail. Always inspect the body:

{
  "errors": [],
  "data": {}
}

Field	Meaning
errors	Empty [] = success. Non-empty = failure messages (often localized).
errorCodes	Present on create-user / archive / archive-resolve. Stable machine codes.
data	Endpoint-specific payload.

Exceptions / variants:

• GET /health-check returns { "status": "ok!", "timestamp": ... } (no errors envelope).
• Clock shift responses use a slightly different shape (error vs errors in some paths).
• Expense receipt returns Msg / MsgType / Data from the report service.
• Some report endpoints return report-service envelopes rather than the generic {errors,data} shape.

Assignment endpoints (customers, projects, account codes) are additive / subtractive, not full replace. Invalid or read-only IDs fail the entire batch.

DELETE requests have no body. Pass ID lists as query parameters on collection endpoints, or in the path on single-item endpoints.

---

---

5. Health & authentication

GET /health-check

No authentication. Use for uptime probes.

curl -s "$API_BASE/health-check"
# {"status":"ok!","timestamp":"..."}

POST /auth/token / GET /auth/token

See §2 Authentication.

---

---

6. Server metadata

GET /server/constants

Returns application constants grouped by category (user statuses, access types, payroll codes, record statuses, etc.). Useful when mapping filter enums for list/report endpoints.

curl -s "$API_BASE/server/constants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

GET /server/timezones

curl -s "$API_BASE/server/timezones" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

Use timezone IDs from this list when calling POST /user.

---

API documentation hub