Overview
Definitiv now supports alpha-numeric employee numbers, giving organisations the flexibility to use their existing employee numbering conventions rather than converting to a numeric-only format when onboarding to Definitiv.
Numeric Only — digits only (e.g. 000042). This is the default and reflects existing behaviour.
Alpha-Numeric — letters and digits (e.g. EMP001, ABC123).
This is particularly beneficial for organisations migrating from other HR and payroll systems where alpha-numeric employee identifiers are already in use, eliminating the need to renumber employees during implementation.
What has changed
Two new settings have been added to Organisation Settings:
Setting | Description | Default Value |
Employee Number Format | Controls whether employee numbers must be numeric-only or can contain letters and digits. | Numeric Only |
Minimum Employee Number Length | The minimum number of characters required for an employee number. For Numeric Only organisations, auto-generated numbers are zero-padded to this length. | 6 |
Note: These settings affect the entire organisation. Changing the Employee Number Format applies to all employee creation, update, and import operations going forward. It does not retroactively reformat existing employee numbers.
The following areas of Definitiv have been updated to support alpha-numeric employee numbers:
Employee creation and update (UI)
Integration API (POST/PUT employee endpoints)
Employee Workbook Import
Timesheet, Roster, and External Payroll Transactions imports
TimeClock (Web, iOS, and Android app v2.44 onwards)
Configuring your employee number format
Navigate to Settings → Organisation Settings.
Locate the Employee Number Format dropdown and select either Numeric Only or Alpha-Numeric.
If required, update the Minimum Employee Number Length (default is 6).
Save your changes.
Note: Switching from Numeric Only to Alpha-Numeric is always permitted. Switching from Alpha-Numeric back to Numeric Only, may be blocked - see Switching back to Numeric Only below.
How employee numbers work
Validation
When creating or updating an employee number, Definitiv validates the input against your organisation's configured format:
| Numeric Only | Alpha-Numeric |
Allowed characters | Digits only (0–9) | Letters and digits (A–Z, a–z, 0–9) |
Special characters | Not allowed | Not allowed |
Minimum length | Configurable (default 6) | Configurable (default 6) |
Case sensitivity | N/A | Case-insensitive — |
Note: Special characters such as hyphens (-), underscores (_), and spaces are not supported in employee numbers in either format.
How employee numbers are stored
Numeric Only: Numbers are left-padded with zeros to meet the minimum length. For example, entering
42when the minimum length is 6 stores000042. Numbers already at or above the minimum length are stored as-is.Alpha-Numeric: Numbers are trimmed and converted to uppercase for storage. For example,
emp001is stored asEMP001.
Auto-generated employee numbers
When an employee is created without specifying a number, Definitiv automatically generates the next sequential value by finding the highest existing numeric number in the organisation, incrementing by 1, and zero-padding to the configured minimum length.
Auto-generation always produces a numeric result, even in Alpha-Numeric mode. Alpha-numeric numbers such as EMP001 are ignored when calculating the next auto-generated value.
Switching between formats
Numeric Only to Alpha-Numeric
This switch is always permitted. All existing numeric employee numbers remain valid and are not changed.
Alpha-Numeric to Numeric Only
Switching back to Numeric Only may be blocked. Before allowing the switch, Definitiv checks:
Alpha character check - if any employee numbers contain letters, the switch is blocked and the affected employees are listed.
Canonical collision check - if two employee numbers that appear different would become the same identity in Numeric Only mode (for example,
42and000042both represent 42), the switch is blocked and up to 3 examples are shown.
To resolve a blocked switch, update all affected employee numbers to be purely numeric and ensure no canonical collisions exist before attempting the switch again.
Importing employees
The Employee Workbook Import has been updated to support alpha-numeric employee numbers:
Scenario | Behaviour |
New employee with a valid number | Validated against the organisation's format, normalised, and stored. |
New employee with an invalid format | The import row is rejected with a validation error. |
Update - same number, different casing | Original database casing is preserved. For example, if the record has |
Update - genuinely different number | Standard change detection applies - the number is updated and an STP event may be triggered. |
Duplicate detection | Uses normalised comparison to detect collisions across the import batch and existing employees. |
Effects on other areas
Single Touch Payroll (STP)
Employee number changes are reported to the ATO via STP. Definitiv's normalisation logic ensures that cosmetic-only changes - such as re-padding from 42 to 000042, or a case change from emp001 to EMP001 - do not trigger unnecessary STP update events.
TimeClock
Alpha-numeric employee numbers are supported for clock-in across all TimeClock platforms:
Web TimeClock - updated as of V3.28
iOS and Android TimeClock apps - supported from app version 2.44
Integration API
All Integration API endpoints for employee creation (POST /api/employees) and update (PUT /api/employees/{id}) now validate and normalise employee numbers against the organisation's format settings. Existing integrations sending numeric-only values will continue to work without any changes.
Frequently Asked Questions
Can I use both formats within the same organisation?
No. Employee number format is a single Definitiv organisation-wide setting, though different organisations in Definitiv can have different formats selected.
What happens to existing employee numbers when I switch to Alpha-Numeric?
Nothing changes, in Alpha-Numeric mode, purely numeric employee numbers are still valid - so existing numeric numbers do not need to be changed. The switch simply allows new employee numbers to contain letters going forward.
Can an employee number be changed after creation?
Yes. Employee numbers can be updated via the UI or API. The new number must pass validation for the organisation's current format and must not duplicate an existing number.
How does this affect payslips?
Historical payslips retain the employee number that was current at the time they were generated. Once updated, any newly generated payslips will display the new number.
How does this affect reports?
Reports are built dynamically and display employee numbers as currently stored. In Alpha-Numeric mode, reports will show alpha-numeric values (e.g. EMP001).
Is there a maximum length for employee numbers?
There is no explicit maximum length enforced by Definitiv beyond database column limits. The minimum length is configurable (default 6).