TFN Declaration Validation Rules

This document lists the fields that make up a tax file number declaration and the validation rules that apply to them, including the rules that hold between fields. Many of these rules come directly from the ATO's requirements for TFN declarations.

TFN or exemption, never both

Every declaration carries either a tax file number or a reason the employee is not quoting one:

• tfn is provided alone when the employee has quoted their TFN.
• tfn_exemption_type is provided alone when they have not.
• Providing both, or neither, is invalid.

The TFN itself must be 9 digits and pass the ATO's checksum. Spaces and other non-digit characters are stripped before validation, so 049 333 118 is accepted. The all-zeros placeholder is rejected.

The exemption types are:

Value	Meaning
not_quoted	The employee does not want to quote their TFN to this employer
pending	The employee has applied for a TFN and is waiting to receive it
under_eighteen	The employee is under 18 and does not earn enough to pay tax
pensioner	The employee receives a pension, benefit or allowance

Rules for exempt declarations

An employee who has not quoted a TFN cannot make claims that require one:

• tax_free_threshold_claimed must be false, with one exception. An under_eighteen exemption combined with a date of birth under 18 years may still claim the tax-free threshold.
• has_study_and_training_repayment must be false. Study and training repayments can only be withheld against a quoted TFN.

has_financial_supplement_debt is not restricted by exemption status.

Residency rules

residency_type is one of australian_resident_for_tax_purposes, foreign_resident or working_holiday_maker.

• country_of_origin is required for foreign residents and working holiday makers, in ISO 3166-1 alpha-3 format (for example nzl). It is not used for Australian residents.
• Only australian_resident_for_tax_purposes may claim the tax-free threshold. Claiming it as a foreign resident or working holiday maker is invalid. The under-18 exception described above also applies here.

Personal details

• title, given_name, family_name and date_of_birth are required. middle_name is optional.
• When title is other, title_other must describe the title.
• All name fields are limited to 40 characters by the ATO and are trimmed of surrounding whitespace.
• Previous names travel together. Supplying either previous_given_name or previous_family_name requires both, because a previous name on the TFN declaration form is a whole name rather than two independent fields. Omitting both records no previous name.
• date_of_birth is an ISO 8601 date. The employee must be at least 12 years old and no older than 120.

Address

• address_line_1, locality, postcode and state are required. address_line_2 is optional.
• Address lines are limited to 50 characters by the ATO. Characters that cannot appear in an ATO address (such as <, >, &, quotes and brackets) are rejected.
• locality accepts letters, numbers and spaces only.
• postcode must be a valid four digit Australian postcode.

Other tax details

• pay_basis is required and is one of full_time, part_time, casual, labour_hire or non_employee.
• tax_free_threshold_claimed, has_study_and_training_repayment and has_financial_supplement_debt are required booleans, subject to the exemption and residency rules above.

Declarations

• declaration_tfnd_accepted and declaration_information_accepted must both be true. These record the employee's acceptance and the declaration is invalid without them.
• declaration_stapling_accepted must be supplied. It records whether the employer has accepted the stapling declaration.

Getting help

Stuck with something and need help? Please contact us at support@superapi.com.au or by phone on 0405 472 748 (Sam). Have you setup a shared Slack or Teams channel with us? If not, please reach out so we can provide realtime support.