SD Worx (BE SME Payroll) – Gotchas

id is the SD Worx employer file number (for example 1AB1234), an alphanumeric payroll-file code. Only legal_name, display_name and status are available; addresses, phone numbers, emails, websites, currency, company_number and timestamps are not. status is active while the payroll file has no end date and inactive once it has one.

The list contains every employer (payroll file) the integration's registered client may access, and it is returned in full on every call; limit and cursor page through that list. An employee connection reads one employer at a time: the employer_file_number connection setting picks one of these records.

id is the SD Worx employer file number (for example 1AB1234). Only legal_name, display_name and status are available; status is active while the payroll file has no end date and inactive once it has one. An unknown employer file number returns a 404.

Listing employees requires the employer_file_number connection setting: it selects the SD Worx payroll file (employer) whose employees are returned. The available employers are the records of the companies resource.

Only employees with an active contract are returned, so terminated employees never appear; employment_status is terminated only for a contract whose leaving date has already passed. department, manager, team, bank_accounts and photo_url are not available.

Employees cannot be filtered or sorted: any filter[...] or sort[...] parameter is rejected with a 400. limit and cursor work. Every page assembles person and contract details from several vendor calls, so a list call takes a few seconds. Listing without the employer_file_number setting returns a 400 that names the setting; an employer the connection cannot access returns a 404.

If one of the detail calls fails, the request still succeeds with a 200 and the fields that call provides (for example gender, birthday, jobs, compensations or the employment dates) are absent. Treat their absence as unavailable for this request, not as empty at the source. One record is returned per person; when a person holds several concurrent contracts with the employer, the details of the first contract are used.

id is the SD Worx person id and employee_number the payroll employee number. title, jobs, employment_start_date, employment_end_date, employment_role.type and compensations come from the contract valid on the day of the request; wages are returned in EUR per hour, month or (as other) per day. jobs is empty when the contract has no job description in SD Worx.

gender is derived from SD Worx's gender code table (male, female, or not_specified for unknown and not disclosed). preferred_language and languages are normalised to ISO 639-1 codes (nl, fr, de, en), nationalities are ISO 3166-1 alpha-2 codes and marital_status carries the SD Worx marital-status code (for example 02 for married). Belgian addresses split the house number and the box number: addresses[].line1 holds the street and house number and addresses[].line2 holds the box number.

id is the SD Worx person id. Reading an employee requires the employer_file_number connection setting (a 400 names it when missing); employee_number, company_id, title, jobs, compensations, employment_start_date, employment_end_date and employment_role come from the person's active contract for that employer, valid on the day of the request, and are absent when the person has none. The record is assembled from several vendor calls: if one fails the request still succeeds with a 200 and that call's fields are absent, so treat absence as unavailable for this request. jobs is empty when the contract has no job description.

department, manager, team, bank_accounts, photo_url and updated_at are not available.

gender is derived from SD Worx's gender code table (male, female, or not_specified for unknown and not disclosed); preferred_language and languages are ISO 639-1 codes, nationalities ISO 3166-1 alpha-2 codes and marital_status the SD Worx marital-status code (for example 02 for married). addresses[].line1 holds the street and house number and addresses[].line2 holds the Belgian box number.