Response format & errors

Response envelope, HTTP errors, dates and request sizing.

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 or expired token)
`403`	Forbidden (no access to company or resource)
`404`	Not found
`409`	Conflict (for example, already clocked in or not currently clocked in)
`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 payroll period at a time

Dates & timezones

Use	Format	Example
Query `startDate`, `endDate`	`yyyy-MM-dd`	`2026-08-01`
Punch timestamps `startAtUtc`, `endAtUtc`	ISO-8601 UTC	`2026-08-25T08:00:00Z`

Timesheets use the company timezone where applicable.

Data minimization

Public integration responses are limited to the fields required for the documented operation. Administrative configuration, credentials and unrelated personal data are not included.