Dokumentacja API

Zasoby

Pracownicy

Odczyt kartotek, eksport gotowych plików kadrowych, aktualizacja pól i dwukierunkowa synchronizacja z programem kadrowym. Zapisy nie tworzą nowych pracowników — aktualizują dopasowanych (merge zachowawczy).

Model kanoniczny

W środku utrzymujemy jeden kanoniczny model pracownika, z którego budowane są wszystkie eksporty. Import i PATCH nigdy nie zerują danych — uzupełniają tylko puste lub zmienione pola. Zakładanie pracownika od zera odbywa się osobnym przepływem onboardingu.

GET`/employees`

read:employees

Lista pracowników tenanta (dane podsumowujące, bez odszyfrowanego PII). Odpowiedź jest stronicowana.

Parametry zapytania

`status` stringopcjonalne	filtr po statusie onboardingu (np. completed).
`companyId` uuidopcjonalne	ogranicz do jednej firmy (płatnika).
`updatedSince` ISO-8601opcjonalne	tylko rekordy zmienione od podanego momentu — do synchronizacji przyrostowej.
`page` integeropcjonalne	numer strony (domyślnie 1).
`pageSize` integeropcjonalne	rozmiar strony (domyślnie 50, maks. 200).

Żądanie · cURL

curl -H "Authorization: Bearer onb_..." \
  "https://www.onboardly.work/api/v1/employees?updatedSince=2026-07-01&pageSize=50"

Odpowiedź 200 · JSON

{
  "data": [{
    "id": "uuid", "firstName": "Jan", "lastName": "Kowalski",
    "email": "jan@example.com", "phone": "+48…", "status": "completed",
    "contractType": "zlecenie", "isForeigner": false, "nationalityType": null,
    "position": "Kelner", "companyId": "uuid",
    "startDate": "2026-06-01", "endDate": null,
    "updatedAt": "2026-07-10T12:00:00.000Z"
  }],
  "page": 1, "pageSize": 50, "total": 130, "totalPages": 3
}

GET`/employees/{id}`

read:employees

Pełna kartoteka kanoniczna z odszyfrowanymi danymi osobowymi. Każde wywołanie loguje dostęp do PII (RODO art. 30).

Odpowiedź 200 (fragment) · JSON

{
  "data": {
    "onboardingId": "uuid", "status": "completed",
    "firstName": "Jan", "lastName": "Kowalski", "email": "…", "phone": "…",
    "pesel": "86010112345", "birthDate": "1986-01-01", "placeOfBirth": "Warszawa",
    "nationality": "PL", "isForeigner": false,
    "residenceAddress": { "street": "…", "houseNumber": "…", "postalCode": "00-001", "city": "Warszawa", "country": "PL" },
    "contractType": "zlecenie", "position": "Kelner",
    "occupationCode": "941201", "startDate": "2026-06-01", "endDate": null,
    "hourlyRate": 30.0, "bankAccount": "PL…", "bankName": "mBank",
    "insurance": { "code": "041100", "confidence": "low", "requiresZusRegistration": true, "document": "ZUA" },
    "nfzCode": "07", "pit2": true, "ppkResign": false,
    "employer": { "name": "…", "nip": "…", "regon": "…", "address": "…" }
  }
}

HTTP	code	Znaczenie
`404`	`not_found`	brak pracownika w tym tenancie.
`410`	`pii_deleted`	dane osobowe usunięte (RODO).

GET`/employees/{id}/export?format=`

read:employees

Zwraca gotowy plik (nie JSON) dla programu kadrowego. Nagłówek Content-Disposition: attachment; ewentualne ostrzeżenia w nagłówku X-Payroll-Warnings (URL-encoded JSON).

Parametr zapytania

format

enumopcjonalne

kedu | optima | symfonia | csv | xlsx (domyślnie kedu). KEDU to uniwersalne zgłoszenie ZUS czytane przez Płatnik, Optima, Symfonia, enova i Gratyfikant.

cURL

curl -H "Authorization: Bearer onb_..." \
  "https://www.onboardly.work/api/v1/employees/{id}/export?format=kedu" -o kedu.xml

HTTP	code	Znaczenie
`400`	—	nieznany format.
`422`	`incomplete`	brak wymaganych pól — ciało zawiera { blockers[], warnings[] }.
`501`	`format_not_ready`	format jeszcze niegotowy dla tej ścieżki.

GET`/employees/{id}/ift?year=`

read:employees

Dane do informacji IFT-1/IFT-1R (nierezydent): dane osobowe, zagraniczny TIN, adres zagraniczny, rachunek (IBAN + SWIFT/BIC), certyfikat rezydencji, dokumenty legalizacyjne z datami ważności oraz suma przychodów i pobranego podatku z rachunków wskazanego roku.

Parametr zapytania

year

stringopcjonalne

Rok podatkowy (domyślnie bieżący), np. 2026.

cURL

curl -H "Authorization: Bearer onb_..." \
  "https://www.onboardly.work/api/v1/employees/{id}/ift?year=2026"

HTTP	code	Znaczenie
`400`	`not_foreigner`	pracownik nie jest cudzoziemcem — IFT nie dotyczy.
`404`	`not_found`	nie znaleziono pracownika.

PATCH`/employees/{id}`

write:employees

Aktualizacja pól kadrowych (kolumny płaskie). Wszystkie pola opcjonalne. PII i adres nie są edytowane tą drogą.

Ciało żądania

`position` stringopcjonalne	stanowisko.
`salaryNet` numberopcjonalne	wynagrodzenie netto.
`hourlyRate` numberopcjonalne	stawka godzinowa.
`startDate / endDate` YYYY-MM-DDopcjonalne	daty zatrudnienia.
`nfzCode / nfzBranch` stringopcjonalne	kod i oddział NFZ.
`usName / usCode` stringopcjonalne	nazwa i kod urzędu skarbowego.
`bankName` stringopcjonalne	nazwa banku.
`nip` stringopcjonalne	NIP pracownika (B2B / PIT-11).
`pit2 / ppkResign` booleanopcjonalne	oświadczenie PIT-2 / rezygnacja z PPK.

cURL

curl -X PATCH -H "Authorization: Bearer onb_..." -H "Content-Type: application/json" \
  -d '{"nfzCode":"07","bankName":"mBank","pit2":true}' \
  "https://www.onboardly.work/api/v1/employees/{id}"

Odpowiedź 200 · JSON

{ "ok": true, "updated": ["nfzCode", "bankName", "pit2"] }

HTTP	code	Znaczenie
`400`	`invalid`	nieprawidłowa wartość pola.
`400`	`empty`	brak pól do aktualizacji.
`404`	`not_found`	brak pracownika w tym tenancie.

POST`/employees/import`

write:employees

Podgląd importu — nic nie zapisuje. Parsuje plik i dopasowuje rekordy po PESEL (fallback: imię + nazwisko + data urodzenia).

Ciało żądania

`format` enumwymagane	kedu \| symfonia \| optima \| csv \| xlsx.
`content` stringwymagane	treść pliku (maks. 5 MB).

cURL

curl -X POST -H "Authorization: Bearer onb_..." -H "Content-Type: application/json" \
  -d '{"format":"kedu","content":"<KEDU>...</KEDU>"}' \
  "https://www.onboardly.work/api/v1/employees/import"

Odpowiedź 200 · JSON

{
  "total": 12, "matched": 10, "new": 2,
  "rows": [{
    "name": "Jan Kowalski", "pesel": "860…",
    "matchedOnboardingId": "uuid", "match": "matched"
  }]
}

HTTP	code	Znaczenie
`422`	`parse_failed`	nie udało się sparsować pliku.
`501`	`format_not_ready`	parser formatu niegotowy.

POST`/employees/import/confirm`

write:employees

Zapis importu — merge zachowawczy (uzupełnia tylko puste lub zmienione pola, nigdy nie zeruje). Upsert wyłącznie do dopasowanych i potwierdzonych identyfikatorów. Nie tworzy nowych pracowników.

Ciało żądania

`format` enumwymagane	jak w podglądzie.
`content` stringwymagane	treść pliku.
`confirmIds` uuid[]wymagane	identyfikatory dopasowanych pracowników do zapisania.

Odpowiedź 200 · JSON

{
  "updated": 2, "skipped": 1,
  "updatedDetail": [{ "onboardingId": "uuid", "fields": ["personal.pesel", "nfzCode"] }],
  "skippedDetail": [{ "reason": "brak zmian", "pesel": "…" }]
}

POST`/employees/{id}/zus/deregister`

write:employees

Ustawia datę zakończenia zatrudnienia i zwraca plik KEDU ZWUA (wyrejestrowanie z ZUS). Wymaga wcześniejszego zgłoszenia (ZUA/ZZA).

Ciało żądania

endDate

YYYY-MM-DDwymagane

data zakończenia zatrudnienia.

cURL

curl -X POST -H "Authorization: Bearer onb_..." -H "Content-Type: application/json" \
  -d '{"endDate":"2026-07-31"}' \
  "https://www.onboardly.work/api/v1/employees/{id}/zus/deregister" -o zwua.xml

HTTP	code	Znaczenie
`409`	`not_registered`	B2B / dzieło — brak zgłoszenia, nie ma czego wyrejestrować.
`410`	`pii_deleted`	dane osobowe usunięte (RODO).

Uwagi implementacyjne

• Eksport KEDU obsługuje ZUA/ZZA; RUD (dzieło) jest pomijany (składa się przez PUE ZUS); ZWUA wyłącznie przez endpoint wyrejestrowania.
• Kod tytułu ubezpieczenia dla zleceń bywa confidence: "low" — potwierdź go przed złożeniem w ZUS.
• Import i PATCH nie zakładają pracowników od zera — do tego służy przepływ onboardingu.

GET/employees

GET/employees/{id}

GET/employees/{id}/export?format=

GET/employees/{id}/ift?year=

PATCH/employees/{id}

POST/employees/import

POST/employees/import/confirm

POST/employees/{id}/zus/deregister

Uwagi implementacyjne

Twój następny pracownikonboarding zajmie 15 minut.

GET`/employees`

GET`/employees/{id}`

GET`/employees/{id}/export?format=`

GET`/employees/{id}/ift?year=`

PATCH`/employees/{id}`

POST`/employees/import`

POST`/employees/import/confirm`

POST`/employees/{id}/zus/deregister`

Twój następny pracownik
onboarding zajmie 15 minut.