UKG Pro – Gotchas

UKG Pro serves person data and employment data from two different endpoints, so the employment fields on "List Employees" (employment_status, employment_role, title, department, department_id, employment_start_date, employment_end_date, manager) are enriched from a second call made on your behalf. If that secondary call fails, the request still succeeds with a 200 and those fields are simply absent from the affected records — the person-scope fields are unaffected. Treat their absence as "unavailable for this request", not as "empty at the source". On a list filtered by employment_status the roles are reversed: the second call supplies the person fields, so if it fails the records keep their employment fields while the person fields — including id — may be absent. UKG returns every employee ever employed, including terminated ones. employment_status resolves from the connector's employment status value; use filter[employment_status] to scope the list server-side. The filter accepts active, inactive and terminated — other is rejected because this connector has no status it could match. The filter can be combined with filter[company_id], but not with filter[email], filter[first_name] or filter[last_name] — those combinations are rejected with a 400 rather than returning silently unfiltered results. A filtered list returns one entry per matching employment record, so an employee with more than one matching record appears more than once — dedupe on id if you need unique employees. The unfiltered list keeps its one-entry-per-employee shape and reports each employee's primary employment record, so the same employee can appear under filter[employment_status]=terminated (an older terminated record matched) while the unfiltered list reports them as active. department and department_id both resolve from the connector's organisation-level hierarchy, and division is not currently mapped. jobs, compensations, custom_fields and bank_accounts are only available on "Get Employee".

employment_role is sourced from the UKG employment-details endpoint and is returned only by Get Employee (the detail read), not by List Employees.

employment_role.type is derived from UKG's employeeTypeCode, which is a company-defined code table (configurable per tenant), not a fixed system enum. The codes we translate are: CON → contractor, INT → internship, REG → employee, TMP → temp, SUM → temp, STU → other, TES → other. Any other or unrecognized code returns other because employee types are defined by each UKG customer and vary between tenants.

employment_role.sub_type is derived from fullTimeOrPartTimeCode (F → full_time, P → part_time), falling back to salaryOrHourly (H → hourly), otherwise not_specified. When both are present, fullTimeOrPartTimeCode takes precedence (sub_type holds a single value).

To map your own employeeTypeCode values, add a custom mapping scoped to the getEmploymentDetails request with the JSONPath $['employeeTypeCode'] (do not use the picker-suggested $[*]['employeeTypeCode'] — the [*] form does not populate). The value is returned under custom_mappings.