Dokumentacja API
Dokumentacja API · v1
Onboardly API
REST API do dwukierunkowej wymiany danych pracownika między Onboardly a polskimi programami kadrowo-płacowymi i ZUS. Przewidywalne zasoby, uwierzytelnianie kluczem per tenant, odpowiedzi w JSON i standardowe kody HTTP.
API jest zorganizowane wokół zasobów (pracownicy, listy płac, faktury, rozliczenia) i korzysta z czasowników HTTP zgodnie z konwencją REST. Wszystkie odpowiedzi zwracamy w formacie JSON (poza endpointami eksportu i wyrejestrowania, które zwracają gotowy plik). Kwoty (Decimal) zwracamy jako liczby, daty dzienne w formacie YYYY-MM-DD, a znaczniki czasu jako ISO-8601 w UTC.
Base URL
Wszystkie ścieżki w tej dokumentacji są względne wobec base URL. API jest dostępne wyłącznie po HTTPS.
https://www.onboardly.work/api/v1Wersjonowanie
Wersja API jest częścią ścieżki (/api/v1). Zmiany łamiące kompatybilność trafiają do nowej wersji ścieżki — istniejące integracje działają bez zmian. Aktualna referencja odpowiada stanowi z 2026-07-14.
Pierwsze żądanie
Utwórz klucz API w panelu (/app/settings/api-keys), przypisz mu zakres read:employees i pobierz listę pracowników:
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
}Uwierzytelnianie jest wymagane w każdym żądaniu
Każde wywołanie musi zawierać klucz API tenanta. Szczegóły nagłówków i zakresów opisuje strona Uwierzytelnianie.Konwencje formatu
- • JSON dla wszystkich odczytów i zapisów; nagłówek
Content-Type: application/jsondla żądań z ciałem. - • Pliki (eksport kadrowy, KEDU ZWUA) zwracane jako
Content-Disposition: attachment, nie JSON. - • Kwoty jako liczby (Decimal), waluta PLN.
- • Daty dzienne —
YYYY-MM-DD; znaczniki czasu — ISO-8601 UTC. - • Tenant-scope — klucz jest przypisany do tenanta; widzisz wyłącznie dane swojego tenanta.
Co znajdziesz w dokumentacji
Uwierzytelnianie
Klucze API per tenant, nagłówki, zakresy uprawnień i tenant-scope.
Błędy, limity i paginacja
Kody HTTP, format błędu, rate limiting, nagłówki limitów i audyt PII.
Pracownicy
Lista, kartoteka, eksport pliku kadrowego (KEDU/Optima/Symfonia), dane cudzoziemca do IFT-1/IFT-1R, aktualizacja, import i wyrejestrowanie ZUS.
Listy płac
Listy płac w modelu SoCap za dany miesiąc.
Faktury
Rachunki i faktury pracowników (model Invoice).
Rozliczenia
Rozliczenie projektu z prowizją i danymi faktury.
Webhooki
Zdarzenia onboarding/KYC, podpis HMAC-SHA256 i weryfikacja sygnatury.