API

Response format & errors

Envelope, HTTP status codes, dates and pagination.

All Public Integration API responses use the same envelope.

ApiResponse

{
  "success": true,
  "data": { },
  "errors": null
}
Field Type Description
success boolean true when the request succeeded
data object / array / null Payload; may be {} or []
errors string[] | null Messages when success is false

Error example:

{
  "success": false,
  "data": null,
  "errors": ["startDate and endDate must be valid ISO dates (yyyy-MM-dd)."]
}

HTTP status codes

Code Meaning
200 OK
400 Bad request (invalid format, missing fields)
401 Unauthorized (invalid/expired token, wrong password/PIN)
403 Forbidden (no access to company or resource)
404 Not found
409 Conflict (e.g. already clocked in/out)
429 Too many requests
500 Unexpected server error

Pagination

v1 returns full result sets for the requested period/company. For large companies:

  • Limit startDate / endDate to one pay period
  • Use employeeIds in payroll preview when possible

Cursor/page pagination may be added later.

Dates & timezones

Use Format Example
Query startDate, endDate, from, to yyyy-MM-dd 2026-08-01
Punch timestamps startAtUtc, endAtUtc ISO-8601 UTC 2026-08-25T08:00:00Z
Daily UF / absence maps yyyy-MM-dd (local) keys in dailyExcessMinutesByLocalDate

Timesheets use the company timezone where applicable.

Fields excluded from public HR API

Integration responses are filtered — see Limits & security.

Examples never returned on public HR endpoints:

  • kioskPin, aiCompanionMemory
  • Permission flags (canManageSchedules, etc.)
  • appliedRuleDefinitionJson
  • National ID / address (unless under a separate signed payroll agreement)
  • Integration secrets

Punch endpoints return only punch-relevant data (see Punch clock).