v51

latestOpenAPI 3.0.0MITraw.githubusercontent.com2026-07-213287185.4 KB

PayrollAu

Creates a payroll employee

post/Employees

Headers

Idempotency-Keystring

This allows you to safely retry requests without the risk of duplicate processing. 128 character max.

Request body

FirstNamestring required

First name of employee

LastNamestring required

Last name of employee

DateOfBirthstring required

Date of birth of the employee (YYYY-MM-DD)

StartDatestring

Start date for an employee (YYYY-MM-DD)

Titlestring

Title of the employee

MiddleNamesstring

Middle name(s) of the employee

Emailstring

The email address for the employee

Gender'N' | 'M' | 'F' | 'I'

The employee’s gender. See Employee Gender

Phonestring

Employee phone number

Mobilestring

Employee mobile number

TwitterUserNamestring

Employee’s twitter name

IsAuthorisedToApproveLeaveboolean

Authorised to approve other employees' leave requests

IsAuthorisedToApproveTimesheetsboolean

Authorised to approve timesheets

JobTitlestring

JobTitle of the employee

Classificationstring

Employees classification

OrdinaryEarningsRateIDstring uuid

Xero unique identifier for earnings rate

PayrollCalendarIDstring uuid

Xero unique identifier for payroll calendar for the employee

EmployeeGroupNamestring

The Employee Group allows you to report on payroll expenses and liabilities for each group of employees

EmployeeIDstring uuid

Xero unique identifier for an Employee

TerminationDatestring

Employee Termination Date (YYYY-MM-DD)

TerminationReason'V' | 'I' | 'D' | 'R' | 'F' | 'C' | 'T'

V Voluntary cessation - An employee resignation, retirement, domestic or pressing necessity or abandonment of employment
I Ill health - An employee resignation due to medical condition that prevents the continuation of employment, such as for illness, ill-health, medical unfitness or total permanent disability
D Deceased - The death of an employee
R Redundancy - An employer-initiated termination of employment due to a genuine redundancy or approved early retirement scheme
F Dismissal - An employer-initiated termination of employment due to dismissal, inability to perform the required work, misconduct or inefficiency
C Contract cessation - The natural conclusion of a limited employment relationship due to contract/engagement duration or task completion, seasonal work completion, or to cease casuals that are no longer required
T Transfer - The administrative arrangements performed to transfer employees across payroll systems, move them temporarily to another employer (machinery of government for public servants), transfer of business, move them to outsourcing arrangements or other such technical activities.

IncomeType'SALARYANDWAGES' | 'WORKINGHOLIDAYMAKER' | 'NONEMPLOYEE' | 'CLOSELYHELDPAYEES' | 'LABOURHIRE'

EmploymentType'EMPLOYEE' | 'CONTRACTOR'

CountryOfResidence'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GG' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IM' | 'IL' | 'IT' | 'JM' | 'JP' | 'JE' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KP' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MK' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'ME' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'AN' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'BL' | 'SH' | 'KN' | 'LC' | 'MF' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'RS' | 'SC' | 'SL' | 'SG' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' | 'BQ' | 'CW' | 'SX' | 'SS'

Country of residence as a valid ISO 3166-1 alpha-2 country code e.g. "AU", "NZ", "CA". Only applicable, and mandatory if income type is WORKINGHOLIDAYMAKER.

IsSTP2Qualifiedboolean

Indicates if the employee has been updated for STP Phase 2 compliance. Doesn't indicate that the employee is payable.

Status'ACTIVE' | 'TERMINATED'

Employee Status Types

UpdatedDateUTCstring

Last modified timestamp

Example request

[
  {
    "FirstName": "Karen",
    "LastName": "Jones",
    "DateOfBirth": "/Date(322560000000+0000)/",
    "HomeAddress": {
      "AddressLine1": "123 Main St",
      "AddressLine2": "Apt 4",
      "City": "St. Kilda",
      "Region": "VIC",
      "Country": "AUSTRALIA"
    },
    "StartDate": "/Date(320284900000+0000)/",
    "Title": "Mrs",
    "MiddleNames": "Adena",
    "Email": "developer@me.com",
    "Gender": "F",
    "Phone": "415-555-1212",
    "Mobile": "415-234-5678",
    "TwitterUserName": "xeroapi",
    "IsAuthorisedToApproveTimesheets": true,
    "JobTitle": "Manager",
    "OrdinaryEarningsRateID": "5gj1e5cc-9835-40d5-bb18-09fdb118db9c",
    "PayrollCalendarID": "2ee8e5cc-9835-40d5-bb18-09fdb118db9c",
    "EmployeeGroupName": "marketing",
    "EmployeeID": "4ff1e5cc-9835-40d5-bb18-09fdb118db9c",
    "TerminationDate": "/Date(1584662400000+0000)/",
    "TerminationReason": "F",
    "BankAccounts": [
      {
        "StatementText": "Salary",
        "AccountName": "James Lebron Savings",
        "Amount": 200
      }
    ],
    "PayTemplate": {
      "EarningsLines": [
        {
          "EarningsRateID": "72e962d1-fcac-4083-8a71-742bb3e7ae14",
          "AnnualSalary": 40000,
          "NumberOfUnitsPerWeek": 38,
          "RatePerUnit": 38,
          "NormalNumberOfUnits": 38,
          "Amount": 38,
          "NumberOfUnits": 2.5,
          "FixedAmount": 2.5
        }
      ],
      "DeductionLines": [
        {
          "DeductionTypeID": "59cd9d04-4521-4cc3-93ac-7841651ff407",
          "Amount": 10,
          "Percentage": 10,
          "NumberOfUnits": 10
        }
      ],
      "SuperLines": [
        {
          "SuperMembershipID": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
          "MinimumMonthlyEarnings": 450,
          "Percentage": 9,
          "Amount": 10
        }
      ],
      "ReimbursementLines": [
        {
          "ReimbursementTypeID": "bd246b96-c637-4767-81cf-851ba8fa93c2",
          "Amount": 10,
          "Description": "For the taxi"
        }
      ],
      "LeaveLines": [
        {
          "LeaveTypeID": "742998cb-7584-4ecf-aa88-d694f59c50f9",
          "IncludeSuperannuationGuaranteeContribution": true,
          "IsQualifyingEarnings": true,
          "NumberOfUnits": 2.5,
          "AnnualNumberOfUnits": 2.5,
          "FullTimeNumberOfUnitsPerPeriod": 2.5
        }
      ]
    },
    "OpeningBalances": {
      "OpeningBalanceDate": "/Date(322560000000+0000)/",
      "Tax": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
      "EarningsLines": [
        {
          "EarningsRateID": "72e962d1-fcac-4083-8a71-742bb3e7ae14",
          "AnnualSalary": 40000,
          "NumberOfUnitsPerWeek": 38,
          "RatePerUnit": 38,
          "NormalNumberOfUnits": 38,
          "Amount": 38,
          "NumberOfUnits": 2.5,
          "FixedAmount": 2.5
        }
      ],
      "DeductionLines": [
        {
          "DeductionTypeID": "59cd9d04-4521-4cc3-93ac-7841651ff407",
          "Amount": 10,
          "Percentage": 10,
          "NumberOfUnits": 10
        }
      ],
      "SuperLines": [
        {
          "SuperMembershipID": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
          "MinimumMonthlyEarnings": 450,
          "Percentage": 9,
          "Amount": 10
        }
      ],
      "ReimbursementLines": [
        {
          "ReimbursementTypeID": "bd246b96-c637-4767-81cf-851ba8fa93c2",
          "Amount": 10,
          "Description": "For the taxi"
        }
      ],
      "LeaveLines": [
        {
          "LeaveTypeID": "742998cb-7584-4ecf-aa88-d694f59c50f9",
          "NumberOfUnits": 2.5
        }
      ],
      "PaidLeaveEarningsLines": [
        {
          "LeaveTypeID": "742998cb-7584-4ecf-aa88-d694f59c50f9",
          "Amount": 500,
          "SGCAppliedLeaveLoadingAmount": 50,
          "SGCExemptedLeaveLoadingAmount": 60,
          "ResetSTPCategorisation": true
        }
      ]
    },
    "TaxDeclaration": {
      "EmployeeID": "123 Main St",
      "AustralianResidentForTaxPurposes": true,
      "TaxOffsetEstimatedAmount": 100,
      "UpwardVariationTaxWithholdingAmount": 50,
      "ApprovedWithholdingVariationPercentage": 75,
      "HasStudentStartupLoan": true,
      "HasLoanOrStudentDebt": true,
      "UpdatedDateUTC": "/Date(1583967733054+0000)/",
      "IncludeLeaveLoadingInQualifyingEarnings": true
    },
    "CountryOfResidence": "AU",
    "IsSTP2Qualified": true,
    "LeaveBalances": [
      {
        "LeaveName": "Annual Leave",
        "LeaveTypeID": "544d9292-4329-4512-bfff-a9f15236d776",
        "NumberOfUnits": 81.2602,
        "TypeOfUnits": "Hours"
      }
    ],
    "SuperMemberships": [
      {
        "SuperMembershipID": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
        "SuperFundID": "2187a42b-639a-45cb-9eed-cd4ae488306a"
      }
    ],
    "UpdatedDateUTC": "/Date(1583967733054+0000)/"
  }
]

Response

A successful request

Example response

{
  "Employees": [
    {
      "FirstName": "Karen",
      "LastName": "Jones",
      "DateOfBirth": "/Date(322560000000+0000)/",
      "HomeAddress": {
        "AddressLine1": "123 Main St",
        "AddressLine2": "Apt 4",
        "City": "St. Kilda",
        "Region": "VIC",
        "Country": "AUSTRALIA"
      },
      "StartDate": "/Date(320284900000+0000)/",
      "Title": "Mrs",
      "MiddleNames": "Adena",
      "Email": "developer@me.com",
      "Gender": "F",
      "Phone": "415-555-1212",
      "Mobile": "415-234-5678",
      "TwitterUserName": "xeroapi",
      "IsAuthorisedToApproveTimesheets": true,
      "JobTitle": "Manager",
      "OrdinaryEarningsRateID": "5gj1e5cc-9835-40d5-bb18-09fdb118db9c",
      "PayrollCalendarID": "2ee8e5cc-9835-40d5-bb18-09fdb118db9c",
      "EmployeeGroupName": "marketing",
      "EmployeeID": "4ff1e5cc-9835-40d5-bb18-09fdb118db9c",
      "TerminationDate": "/Date(1584662400000+0000)/",
      "TerminationReason": "F",
      "BankAccounts": [
        {
          "StatementText": "Salary",
          "AccountName": "James Lebron Savings",
          "Amount": 200
        }
      ],
      "PayTemplate": {
        "EarningsLines": [
          {
            "EarningsRateID": "72e962d1-fcac-4083-8a71-742bb3e7ae14",
            "AnnualSalary": 40000,
            "NumberOfUnitsPerWeek": 38,
            "RatePerUnit": 38,
            "NormalNumberOfUnits": 38,
            "Amount": 38,
            "NumberOfUnits": 2.5,
            "FixedAmount": 2.5
          }
        ],
        "DeductionLines": [
          {
            "DeductionTypeID": "59cd9d04-4521-4cc3-93ac-7841651ff407",
            "Amount": 10,
            "Percentage": 10,
            "NumberOfUnits": 10
          }
        ],
        "SuperLines": [
          {
            "SuperMembershipID": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
            "MinimumMonthlyEarnings": 450,
            "Percentage": 9,
            "Amount": 10
          }
        ],
        "ReimbursementLines": [
          {
            "ReimbursementTypeID": "bd246b96-c637-4767-81cf-851ba8fa93c2",
            "Amount": 10,
            "Description": "For the taxi"
          }
        ],
        "LeaveLines": [
          {
            "LeaveTypeID": "742998cb-7584-4ecf-aa88-d694f59c50f9",
            "IncludeSuperannuationGuaranteeContribution": true,
            "IsQualifyingEarnings": true,
            "NumberOfUnits": 2.5,
            "AnnualNumberOfUnits": 2.5,
            "FullTimeNumberOfUnitsPerPeriod": 2.5
          }
        ]
      },
      "OpeningBalances": {
        "OpeningBalanceDate": "/Date(322560000000+0000)/",
        "Tax": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
        "EarningsLines": [
          {
            "EarningsRateID": "72e962d1-fcac-4083-8a71-742bb3e7ae14",
            "AnnualSalary": 40000,
            "NumberOfUnitsPerWeek": 38,
            "RatePerUnit": 38,
            "NormalNumberOfUnits": 38,
            "Amount": 38,
            "NumberOfUnits": 2.5,
            "FixedAmount": 2.5
          }
        ],
        "DeductionLines": [
          {
            "DeductionTypeID": "59cd9d04-4521-4cc3-93ac-7841651ff407",
            "Amount": 10,
            "Percentage": 10,
            "NumberOfUnits": 10
          }
        ],
        "SuperLines": [
          {
            "SuperMembershipID": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
            "MinimumMonthlyEarnings": 450,
            "Percentage": 9,
            "Amount": 10
          }
        ],
        "ReimbursementLines": [
          {
            "ReimbursementTypeID": "bd246b96-c637-4767-81cf-851ba8fa93c2",
            "Amount": 10,
            "Description": "For the taxi"
          }
        ],
        "LeaveLines": [
          {
            "LeaveTypeID": "742998cb-7584-4ecf-aa88-d694f59c50f9",
            "NumberOfUnits": 2.5
          }
        ],
        "PaidLeaveEarningsLines": [
          {
            "LeaveTypeID": "742998cb-7584-4ecf-aa88-d694f59c50f9",
            "Amount": 500,
            "SGCAppliedLeaveLoadingAmount": 50,
            "SGCExemptedLeaveLoadingAmount": 60,
            "ResetSTPCategorisation": true
          }
        ]
      },
      "TaxDeclaration": {
        "EmployeeID": "123 Main St",
        "AustralianResidentForTaxPurposes": true,
        "TaxOffsetEstimatedAmount": 100,
        "UpwardVariationTaxWithholdingAmount": 50,
        "ApprovedWithholdingVariationPercentage": 75,
        "HasStudentStartupLoan": true,
        "HasLoanOrStudentDebt": true,
        "UpdatedDateUTC": "/Date(1583967733054+0000)/",
        "IncludeLeaveLoadingInQualifyingEarnings": true
      },
      "CountryOfResidence": "AU",
      "IsSTP2Qualified": true,
      "LeaveBalances": [
        {
          "LeaveName": "Annual Leave",
          "LeaveTypeID": "544d9292-4329-4512-bfff-a9f15236d776",
          "NumberOfUnits": 81.2602,
          "TypeOfUnits": "Hours"
        }
      ],
      "SuperMemberships": [
        {
          "SuperMembershipID": "4333d5cd-53a5-4c31-98e5-a8b4e5676b0b",
          "SuperFundID": "2187a42b-639a-45cb-9eed-cd4ae488306a"
        }
      ],
      "UpdatedDateUTC": "/Date(1583967733054+0000)/"
    }
  ]
}