API docs
Introduction
Errors, limits & pagination
The API uses conventional HTTP status codes and a predictable error format. Below is the full set of codes, the rate limiting rules and how lists are paginated.
Error format
Errors are returned as JSON with a human-readable description and a machine-readable code you can safely branch your integration logic on:
{
"error": "klucz nie ma wymaganego zakresu",
"code": "forbidden_scope"
}Response codes
Codes in the 2xx range mean success, 4xx — an error on the request side (data, permissions, limit).
| HTTP | code | Znaczenie |
|---|---|---|
401 | unauthorized | missing or invalid API key. |
403 | forbidden_scope | the key lacks the scope required by the endpoint. |
404 | not_found | the resource does not exist in this tenant. |
410 | pii_deleted | personal data has been deleted (GDPR) — the record is unavailable. |
422 | incomplete / parse_failed / export_failed | incomplete data or a processing error (e.g. missing required fields during a ZUS export). |
429 | rate_limited | request limit exceeded — see rate limiting. |
Rate limiting
A limit of 120 żądań / min / klucz applies. Once it is exceeded, the API returns 429 rate_limited. Every response includes headers that let you pace your requests:
X-RateLimit-Limit | the maximum number of requests in the window. |
X-RateLimit-Remaining | the number of requests left in the current window. |
X-RateLimit-Reset | the moment the limit resets (epoch, seconds). |
Retrying requests
After receiving a429, wait until the time in the X-RateLimit-Reset header and retry the request (exponential backoff recommended). Do not poll in a loop without a delay.Pagination
The GET /employees endpoint returns data in pages. Control it with the page (default 1) and pageSize (default 50, max 200) parameters. The response includes pagination metadata:
{
"data": [ /* ... */ ],
"page": 1,
"pageSize": 50,
"total": 130,
"totalPages": 3
}Iterate through the pages until page reaches totalPages. For incremental synchronization use the updatedSince filter (see the employees list endpoint).
curl -H "Authorization: Bearer onb_..." \
"https://www.onboardly.work/api/v1/employees?updatedSince=2026-07-01&page=2&pageSize=100"PII audit
Every read or export of a record with decrypted personal data creates an audit entry (GDPR art. 30). List reads (without PII) do not generate an entry.