API docs

Resources

Employees

Read records, export ready-to-use payroll files, update fields and sync bidirectionally with your payroll software. Writes never create new employees — they update matched ones (conservative merge).

Canonical model

Internally we keep a single canonical employee model from which all exports are built. Import and PATCH never wipe data — they only fill in empty or changed fields. Creating an employee from scratch happens through a separate onboarding flow.

GET`/employees`

read:employees

List of the tenant's employees (summary data, without decrypted PII). The response is paginated.

Query parameters

`status` stringopcjonalne	filter by onboarding status (e.g. completed).
`companyId` uuidopcjonalne	restrict to a single company (payer).
`updatedSince` ISO-8601opcjonalne	only records changed since the given moment — for incremental sync.
`page` integeropcjonalne	page number (default 1).
`pageSize` integeropcjonalne	page size (default 50, max 200).

Request · cURL

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

Response 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

Full canonical record with decrypted personal data. Every call logs the PII access (GDPR art. 30).

Response 200 (excerpt) · 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`	no such employee in this tenant.
`410`	`pii_deleted`	personal data deleted (GDPR).

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

read:employees

Returns a ready-to-use file (not JSON) for your payroll software. The Content-Disposition: attachment header; any warnings in the X-Payroll-Warnings header (URL-encoded JSON).

Query parameter

format

enumopcjonalne

kedu | optima | symfonia | csv | xlsx (default kedu). KEDU is the universal ZUS filing read by Płatnik, Optima, Symfonia, enova and 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`	—	unknown format.
`422`	`incomplete`	required fields missing — the body contains { blockers[], warnings[] }.
`501`	`format_not_ready`	format not yet available for this path.

PATCH`/employees/{id}`

write:employees

Update payroll fields (flat columns). All fields optional. PII and address are not edited this way.

Request body

`position` stringopcjonalne	job title.
`salaryNet` numberopcjonalne	net salary.
`hourlyRate` numberopcjonalne	hourly rate.
`startDate / endDate` YYYY-MM-DDopcjonalne	employment dates.
`nfzCode / nfzBranch` stringopcjonalne	NFZ code and branch.
`usName / usCode` stringopcjonalne	tax office name and code.
`bankName` stringopcjonalne	bank name.
`nip` stringopcjonalne	employee NIP (B2B / PIT-11).
`pit2 / ppkResign` booleanopcjonalne	PIT-2 declaration / PPK opt-out.

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}"

Response 200 · JSON

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

HTTP	code	Znaczenie
`400`	`invalid`	invalid field value.
`400`	`empty`	no fields to update.
`404`	`not_found`	no such employee in this tenant.

POST`/employees/import`

write:employees

Preview of the import — writes nothing. Parses the file and matches records by PESEL (fallback: first name + last name + date of birth).

Request body

`format` enumwymagane	kedu \| symfonia \| optima \| csv \| xlsx.
`content` stringwymagane	file content (max 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"

Response 200 · JSON

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

HTTP	code	Znaczenie
`422`	`parse_failed`	the file could not be parsed.
`501`	`format_not_ready`	format parser not ready.

POST`/employees/import/confirm`

write:employees

Commit the import — conservative merge (fills in only empty or changed fields, never wipes). Upsert exclusively to matched and confirmed identifiers. Does not create new employees.

Request body

`format` enumwymagane	as in the preview.
`content` stringwymagane	file content.
`confirmIds` uuid[]wymagane	identifiers of the matched employees to save.

Response 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

Sets the employment end date and returns a KEDU ZWUA file (ZUS deregistration). Requires a prior registration (ZUA/ZZA).

Request body

endDate

YYYY-MM-DDwymagane

employment end date.

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 / specific-task contract — no registration, nothing to deregister.
`410`	`pii_deleted`	personal data deleted (GDPR).

Implementation notes

• KEDU export supports ZUA/ZZA; RUD (specific-task contract) is skipped (filed via PUE ZUS); ZWUA only through the deregistration endpoint.
• The insurance title code for mandate contracts is sometimes confidence: "low" — confirm it before filing with ZUS.
• Import and PATCH do not create employees from scratch — the onboarding flow is for that.

GET/employees

GET/employees/{id}

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

PATCH/employees/{id}

POST/employees/import

POST/employees/import/confirm

POST/employees/{id}/zus/deregister

Implementation notes

Twój następny pracownikonboarding zajmie 15 minut.

GET`/employees`

GET`/employees/{id}`

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

PATCH`/employees/{id}`

POST`/employees/import`

POST`/employees/import/confirm`

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

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