Employee Record Specification

Australia Variant (Working Draft)

Configuration
Metadata
Fields
Types

Configuration

When importing the following configuration is used to describe what fields are expected and how they should be handled.

Field	Type	Notes
`action`	`action`	The action to take when importing. One of the following: `"insert"` Create a new record for each employee. `"update"` Use the following algorithm when importing each employee: If `target_id` is not null If there is an existing record matching `target_id` Update the record Otherwise raise an error If `employee_code` is not null If there is an existing record matching `employee_code` Update the record Otherwise raise an error Otherwise raise an error `"upsert"` Use the following algorithm when importing each employee: If `target_id` is not null If there is an existing record matching `target_id` Update the record Otherwise raise an error If `employee_code` is not null If there is an existing record matching `employee_code` Update the record Otherwise create a new record Otherwise create a new record
`bank_accounts`	`boolean`	If `true`, all fields the Bank Accounts section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`date_of_birth`	`boolean`	If `true`, all fields the Date of Birth section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`emergency_contacts`	`boolean`	If `true`, all fields the Emergency Contacts section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`full_name`	`boolean`	If `true`, all fields the Full Name section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`gender`	`boolean`	If `true`, all fields the Gender section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`personal_email`	`boolean`	If `true`, all fields the Personal Email section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`personal_phone`	`boolean`	If `true`, all fields the Personal Phone section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`postal_address`	`boolean`	If `true`, all fields the Postal Address section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`profile`	`boolean`	If `true`, all fields the Profile section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`residential_address`	`boolean`	If `true`, all fields the Residential Address section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`super_funds`	`boolean`	If `true`, all fields the Super Funds section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.
`tax_details`	`boolean`	If `true`, all fields the Tax Details section must be included in the file. When performing an update, any `null` values will be considered intentional and the value will be unset.

Metadata

The following fields must always be present (even if they all contain null values).

Field	Type	Notes
`employee_code`	`string \| null`	Optional. A unique identifier for the employee within an organisation. If the `target_id` field is not included, this field is used to uniquely identify the employee instead.
`source_id`	`string \| null`	A unique identifier for the employee in the system that generated this file.
`source_system`	`string \| null`	An identifier for the system that generated this file.
`target_id`	`string \| null`	An identifier for the employee in the system that is consuming this file.
`target_system`	`string \| null`	An identifier for the system that is consuming this file.
`updated_at`	`instant \| null`	When this employee record was last modified.

Fields

The fields of each section below must be present if the corresponding configuration field is set to true. Otherwise, they will be ignored and may be omitted.

Bank Accounts

Field	Type	Notes
`bank_account_1_allocation_method`	`allocation_method`
`bank_account_1_allocation`	`decimal`
`bank_account_1_bsb`	`bsb`
`bank_account_1_name`	`string`
`bank_account_1_number`	`string`
`bank_account_2_allocation_method`	`allocation_method`
`bank_account_2_allocation`	`decimal`
`bank_account_2_bsb`	`bsb`
`bank_account_2_name`	`string`
`bank_account_2_number`	`string`
`bank_account_3_allocation_method`	`allocation_method`
`bank_account_3_allocation`	`decimal`
`bank_account_3_bsb`	`bsb`
`bank_account_3_name`	`string`
`bank_account_3_number`	`string`
`bank_account_4_allocation_method`	`allocation_method`
`bank_account_4_allocation`	`decimal`
`bank_account_4_bsb`	`bsb`
`bank_account_4_name`	`string`
`bank_account_4_number`	`string`
`bank_account_5_allocation_method`	`allocation_method`
`bank_account_5_allocation`	`decimal`
`bank_account_5_bsb`	`bsb`
`bank_account_5_name`	`string`
`bank_account_5_number`	`string`

Date of Birth

Field	Type	Notes
`date_of_birth`	`plain_date`

Emergency Contacts

Field	Type	Notes
`emergency_contact_1_name`	`string`
`emergency_contact_1_relationship`	`string`
`emergency_contact_1_phone`	`string`
`emergency_contact_2_name`	`string \| null`
`emergency_contact_2_relationship`	`string \| null`	Must be null if `emergency_contact_2_name` is null. Cannot be null if `emergency_contact_2_name` is not null.
`emergency_contact_2_phone`	`string \| null`	Must be null if `emergency_contact_2_name` is null. Cannot be null if `emergency_contact_2_name` is not null.

Full Name

If any one of the following fields is included, all of the following fields must be included. If a field in included and contains

Field	Type	Notes
`given_name`	`name`	First given name of the employee's legal name.
`other_given_names`	`name \| null`	Other given names of the employee's legal name. Only required if the employee has other given names.
`family_name`	`name`	family name or surname of the employee's legal name.

Gender

Field	Type	Notes
`gender`	`gender`

Personal Email

Field	Type	Notes
`personal_email`	`string`	An email address at which the employee can be contacted. This should be an email address that is not managed by the employer which can be used to contact the employee even after they have ceased working for the employer.

Personal Phone

Field	Type	Notes
`personal_phone`	`string`	A phone number at which the employee can be contacted. This should be a phone number that is not managed by the employer which can be used to contact the employee even after they have ceased working for the employer.

Postal Address

Field	Type	Notes
`postal_address_line_1`	`string`
`postal_address_line_2`	`string \| null`	Optional.
`postal_address_city`	`string`
`postal_address_state`	`state \| string`	Must be a value of `state` if `postal_address_country` is `"Australia"`.
`postal_address_postcode`	`string`
`postal_address_country`	`country_name`

Profile

Field	Type	Notes
`display_name`	`name`	The name the person uses day-to-day.
`profile_email`	`string \| null`	Optional. The employee's email address used at work.
`profile_phone`	`string \| null`	Optional. The employee's phone number used at work.

Residential Address

Field	Type	Notes
`residential_address_line_1`	`string`
`residential_address_line_2`	`string \| null`	Optional.
`residential_address_city`	`string`
`residential_address_state`	`state \| string`	Must be a value of `state` if `residential_address_country` is `"Australia"`.
`residential_address_postcode`	`string`
`residential_address_country`	`country_name`

Super Funds

Field	Type	Notes
`super_fund_1_nomination`	`super_nomination`
`super_fund_1_usi`	`string`
`super_fund_1_member_name`	`string`
`super_fund_1_member_number`	`string`

Tax Details

Field	Type	Notes
`tax_file_number_exemption`	`tax_file_number_exemption`
`tax_file_number`	`tax_file_number \| null`	Can only be null if `tax_file_number_exemption` is not `"none"`.
`residency_status`	`residency_status`
`has_loan_or_student_debt`	`boolean`
`tax_free_threshold_claimed`	`boolean`

Types

Type	Definition
`action`	`"insert" \| "update" \| "upsert"`
`allocation_method`	`"fixed_amount" \| "per_long_hundred" \| "remainder"`
`boolean`
`bsb`	A 6-digit BSB code without spaces or extra characters.
`country_name`	English version of a country's ISO 3166-1:2020 short name in title case (e.g. `"Australia"`).
`decimal`	A decimal number with a precision of 15 and a scale of 6 (e.g. `999999999.999999` or `-0.001`).
`gender`	`"female" \| "male" \| "non_binary" \| "not_stated"`
`instant`	ISO 8601 Date Format with time and offset (e.g. `2020-01-01T16:45:67Z`).
`integer`	A signed 4-byte integer (i.e. `-2147483648` through to `+2147483647`). Positive numbers do not need to include a leading `+` sign.
`name`	Must not contain only numbers. Must not contain two or more hyphens (`-`), apostrophes (`'`), spaces or punctuation marks in a row.
`null`
`plain_date`	ISO 8601 Date Format, no time or time zone (e.g. `2024-01-01`).
`residency_status`	`"australian_resident" \| "foreign_resident" \| "working_holiday_maker"`
`state`	`"ACT" \| "NSW" \| "NT" \| "QLD" \| "SA" \| "TAS" \| "VIC" \| "WA"`
`string`
`super_nomination`	`"not_entitled" \| "employer_nominated" \| "regulated" \| "self_managed"`
`tax_file_number_exemption`	`"none" \| "pending" \| "pensioner" \| "under_18"`
`tax_file_number`	One of the following: A checksum validated 9-digit TFN without spaces or extraneous characters. An obfuscated TFN in the form `"xxxxxxxxx"` to indicate the TFN is on record, but cannot be exported for privacy reasons.