Documentation
What's NewUKG.comMarketplaceUKG Pro status

Employee Synchronization

This section describes employee synchronization.

Employee synchronization

Description

In UKG HR Service Delivery, employees must be registered to create their profile, employee folder, and any personal vaults. Registration provides a unique employee identifier, contact details (email and postal address), and associates each employee with one or more organizations (those organizations should already exist via Organization synchronization). Registration is also used to define one or more employee numbers used as unique identifiers in UKG HR Service Delivery.

Import file

Format

Employee directory synchronization is performed by importing a UTF-8 CSV file, either manually in the admin UI or automatically via SFTP (upload to in/sal). Imports can be incremental (new/updated employees only; others untouched) or complete (all employees; existing updated only if changes are detected). Keep the directory up to date by importing regularly; employees can also be added manually at any time.
Note: If a text field must contain the delimiter ;, wrap the value in single quotes '...' and escape apostrophes by doubling them (e.g., John's ID → 'John''s ID').

Structure

The first row (header) must follow these rules:

  • Mandatory attributes: must all be present and in the documented order (names may vary). There are 41 mandatory attributes.
    Example header positions: 1;2;…;41
  • Optional attribute: if present, it must come after the mandatory attributes and use the documented name (e.g., saml_token).
  • Custom fields: if configured for your tenant, add one column per custom field after the optional attribute (order among custom fields does not matter).

Mandatory attributes (1–41)

  1. organization_code — Code of the organization tied to the employee number.
  2. registration_reference — Employee number within that organization.
  3. technical_id — Unique employee ID from your HRIS (recommended if available).
  4. lastname — Employee last name.
  5. maiden_name — Employee maiden name.
  6. firstname — Employee first name.
  7. professional_email — Professional email (strongly recommended for electronic vault activation; non-ASCII emails not supported).
  8. mark_inactive_former_registration_references — If set, mark former registration references inactive and set their departure date to the import date.
  9. leave_empty_1 (deprecated).
  10. dob — Date of birth (used for duplicate checks; recommended).
  11. address1 — Street address. Required for vault invitation by mail if no email.
  12. address2 — Address line 2.
  13. address3 — Additional address details.
  14. zip_code — Postal code (required for postal invitations if no email).
  15. city — City (required for postal invitations if no email).
  16. country — ISO-3166-1 alpha-2 (e.g., FR, US). If US or CA, state becomes mandatory.
  17. phone_number — International format (e.g., 0018005550111).
  18. mobile_phone_number — International format; used by default for e-signature if no other number is given via API.
  19. middle_name — Middle name.
  20. legal_firstname — Legal first name; mandatory if the “Preferred & Legal first name” setting is enabled.
  21. disable_vault — If set, disables the employee’s vault.
  22. state — Mandatory for US/CA only.
  23. language — IETF BCP-47 (e.g., en-us).
  24. starting_date — Employee start date.
  25. opt_out_from_electronic_payslips — Y=opted out; N=not opted out.
    26–39. leave_empty_3 … leave_empty_16 (deprecated).
  26. disable_distribution — X=no paper/electronic; E=no electronic; P=no paper.
  27. departure_date — If a non-date is provided, employee considered a former employee effective the import date.

Optional attribute

  • saml_token — SAML identifier for SSO.

Custom fields

Custom employee attributes must be added to the file—one column per custom field.

Example of a complete CSV file

Header + rows as per specification (see documentation).

Report file

Reports are XML and include: JOB_REFERENCE, JOB_REPORT_TIMESTAMP, JOB_DESCRIPTION, JOB_TYPE (sal), COUNT_ROWS, and MESSAGE per line.

Example

<EMPLOYEE_REPORT version="1.0">
<JOB_REFERENCE>cmpx0pfLB.csv</JOB_REFERENCE>
<JOB_REPORT_TIMESTAMP>2021-03-19T13:05:50.648461+00:00</JOB_REPORT_TIMESTAMP>
<JOB_DESCRIPTION>Employees import DEMO</JOB_DESCRIPTION>
<JOB_TYPE>sal</JOB_TYPE>
<COUNT_ROWS>3</COUNT_ROWS>

<ENTITY_ID>193930</ENTITY_ID>
<ENTITY_TYPE>Employee</ENTITY_TYPE>
<RESULT_CODE>0</RESULT_CODE>
<RESULT_MESSAGE>Employee Cyrille CHAPELLE Created</RESULT_MESSAGE>

</EMPLOYEE_REPORT>

Registration report

Not enabled by default; can be delivered periodically via a specific setting. Lists employees and whether they opted in/out of paperless delivery.

Format

Includes client_code, client_document_type_code, client_name, date_start, date_end, subscription counts, and per-employee subscription details.

Example

<subscriptions_report version="1.2">
<client_code>acme.people-doc.fr</client_code>
<client_document_type_code>bulsal</client_document_type_code>
…
</subscriptions_report>

Updated 3 months ago