API docs
API documentation · v1
Onboardly API
A REST API for the two-way exchange of employee data between Onboardly and Polish HR/payroll software and ZUS. Predictable resources, per-tenant API key authentication, JSON responses and standard HTTP status codes.
The API is organized around resources (employees, payrolls, invoices, settlements) and uses HTTP verbs following REST conventions. All responses are returned as JSON (except the export and deregistration endpoints, which return a ready-made file). Amounts (Decimal) are returned as numbers, calendar dates in the format YYYY-MM-DD, and timestamps as ISO-8601 in UTC.
Base URL
All paths in this documentation are relative to the base URL. The API is available over HTTPS only.
https://www.onboardly.work/api/v1Versioning
The API version is part of the path (/api/v1). Breaking changes go into a new path version — existing integrations keep working unchanged. The current reference reflects the state as of 2026-07-14.
Your first request
Create an API key in the panel (/app/settings/api-keys), assign it the read:employees scope and fetch the list of employees:
curl -H "Authorization: Bearer onb_..." \
"https://www.onboardly.work/api/v1/employees?pageSize=50"{
"data": [
{
"id": "uuid",
"firstName": "Jan",
"lastName": "Kowalski",
"status": "completed",
"contractType": "zlecenie",
"updatedAt": "2026-07-10T12:00:00.000Z"
}
],
"page": 1,
"pageSize": 50,
"total": 130,
"totalPages": 3
}Authentication is required on every request
Every call must include the tenant's API key. Header and scope details are described on the Authentication page.Format conventions
- • JSON for all reads and writes; the
Content-Type: application/jsonheader for requests with a body. - • Files (HR export, KEDU ZWUA) are returned as
Content-Disposition: attachment, not JSON. - • Amounts as numbers (Decimal), currency PLN.
- • Calendar dates —
YYYY-MM-DD; timestamps — ISO-8601 UTC. - • Tenant scope — the key is assigned to a tenant; you only see your own tenant's data.