---
url: /software_partners/build/modules/tfn_declaration_validations.md
---
# 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.

If you don't use our tax details module and send the employee's details through the API instead, see [Submit a TFN declaration without the tax details module](/software_partners/build/modules/submit_tfnd_without_the_tfnd_module/index.html). That guide covers what to send and how these rules differ when SuperAPI completes the declaration for you.

## 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.

## 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` and `has_study_and_training_repayment` 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.