Submit a TFN declaration without the tax details module

Use this guide if your onboarding shows the superannuation choice module but not our tax details module. For example, you collect TFN details in your own system.

In this setup, you send us the employee's details when you create the employee or the onboarding session. When the employee opens their onboarding session, SuperAPI:

1. Submits the TFN declaration to the ATO on the employee's behalf.
2. Once the ATO accepts it, requests the employee's stapled super fund.

Stapling depends on the TFN declaration. If a detail the declaration needs is missing or invalid, the declaration is not submitted and no stapling request is made. The employee can still complete super choice, but they won't see their stapled fund.

Before you start

• The employer has activated super stapling and clicked "Check ATO connection" in the employer portal. The same ATO connection covers TFN declarations.
• The employee has an email address. Both endpoints below already require one.

A TFN declaration is only submitted once per employee. If one has already been lodged for this employee through SuperAPI, a new onboarding session doesn't submit another.

What to send

Send the three objects a TFN declaration is built from:

• identity
• address
• tax_detail

The fields in each object are described in our API reference for creating an onboarding session and creating an employee. The TFN declaration validation rules say which of those fields a declaration needs and how they relate. The rules there apply with two differences, because SuperAPI completes the declaration for you:

• title is optional.
• You don't send the declaration_* acceptances.

Three things catch people out:

Send booleans even when they are false. A boolean you leave out is stored as empty, not as false, and the declaration fails validation.

Send each object complete, every time. A later request that includes identity, address or tax_detail replaces what we hold for that object. Any field you leave out of it is cleared. Objects you don't send are kept.

The object is tax_detail, not tax_details. An unrecognised key is ignored without an error, so the request still succeeds. Check that tax_detail in the response isn't null.

Example: creating an onboarding session

Send the details in employee_detail.data. This example uses phone_and_super, a standard workflow that includes superannuation choice without the tax details module.

curl -X POST https://api.superapi.com.au/api/v1/onboarding-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "employer": {
      "id": "6739b9e4-22bb-41f0-89d1-e4170710cba8"
    },
    "employee": {
      "remote_id": "employee-2"
    },
    "email": "employee2@example.com",
    "email_validated": true,
    "remote_id": "session-1",
    "workflow_slug": "phone_and_super",
    "employee_detail": {
      "data": {
        "identity": {
          "title": "ms",
          "given_name": "Jane",
          "family_name": "Citizen",
          "date_of_birth": "1990-04-21"
        },
        "address": {
          "address_line_1": "1 Example Street",
          "locality": "Melbourne",
          "postcode": "3000",
          "state": "vic"
        },
        "tax_detail": {
          "tfn": "049333118",
          "residency_type": "australian_resident_for_tax_purposes",
          "pay_basis": "full_time",
          "tax_free_threshold_claimed": true,
          "has_study_and_training_repayment": false
        }
      }
    }
  }'

The response echoes the details we stored under data.employee. Trimmed to the relevant parts:

{
  "data": {
    "id": "5e0a208b-c25f-43ee-be83-aef4860ae298",
    "remote_id": "session-1",
    "employee_id": "23bf86e9-eaa7-4b0b-b1b6-d8b313798071",
    "employee": {
      "id": "23bf86e9-eaa7-4b0b-b1b6-d8b313798071",
      "remote_id": "employee-2",
      "identity": {
        "title": "ms",
        "given_name": "Jane",
        "middle_name": null,
        "family_name": "Citizen",
        "date_of_birth": "1990-04-21",
        "gender": null
      },
      "address": {
        "address_line_1": "1 Example Street",
        "address_line_2": null,
        "locality": "Melbourne",
        "postcode": "3000",
        "state": "vic"
      },
      "tax_detail": {
        "tfn": "049333118",
        "tfn_exemption_type": null,
        "residency_type": "australian_resident_for_tax_purposes",
        "country_of_origin": null,
        "pay_basis": "full_time",
        "tax_free_threshold_claimed": true,
        "has_study_and_training_repayment": false
      }
    }
  },
  "version": "v1"
}

Example: creating an employee

If you create the employee before the onboarding session, send the same objects in data:

curl -X POST https://api.superapi.com.au/api/v1/employer/6739b9e4-22bb-41f0-89d1-e4170710cba8/employee \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "email": "employee@example.com",
    "remote_id": "employee-1",
    "data": {
      "identity": {
        "title": "ms",
        "given_name": "Jane",
        "family_name": "Citizen",
        "date_of_birth": "1990-04-21"
      },
      "address": {
        "address_line_1": "1 Example Street",
        "locality": "Melbourne",
        "postcode": "3000",
        "state": "vic"
      },
      "tax_detail": {
        "tfn": "049333118",
        "residency_type": "australian_resident_for_tax_purposes",
        "pay_basis": "full_time",
        "tax_free_threshold_claimed": true,
        "has_study_and_training_repayment": false
      }
    }
  }'

The response has the same identity, address and tax_detail objects under data. When you later create an onboarding session for this employee, you don't need to send these objects again.

If details are missing or invalid

• The onboarding session still loads and the employee isn't blocked.
• The TFN declaration isn't submitted, and no stapling request is made for the employee.

If you've sent the details above but aren't seeing stapled funds come through, get in touch. We can check your recent onboarding sessions and tell you which details didn't pass.

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.