Sign in
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)/"
    }
  ]
}

Changes

Changed in 3 of the 54 revisions of this API.5149

  • f9c1d353a79411See the full diff
    • ▲

      the request property items/PayTemplate/LeaveLines/items/IsQualifyingEarnings became required

      request-property-became-required

    • ○

      the response property Employees/items/PayTemplate/LeaveLines/items/IsQualifyingEarnings became required for the status 200

      response-property-became-required

  • d1b43af7b70d144See the full diff
    • ●

      removed the request property items/LeaveLines

      request-property-removed

    • ●

      removed the request property items/OpeningBalances/LeaveLines/items/AnnualNumberOfUnits

      request-property-removed

    • ●

      removed the request property items/OpeningBalances/LeaveLines/items/CalculationType

      request-property-removed

    • ●

      removed the request property items/OpeningBalances/LeaveLines/items/EmploymentTerminationPaymentType

      request-property-removed

    • ●

      removed the request property items/OpeningBalances/LeaveLines/items/EntitlementFinalPayPayoutType

      request-property-removed

    • ●

      removed the request property items/OpeningBalances/LeaveLines/items/FullTimeNumberOfUnitsPerPeriod

      request-property-removed

    • ●

      removed the request property items/OpeningBalances/LeaveLines/items/IncludeSuperannuationGuaranteeContribution

      request-property-removed

    • ●

      removed the optional property Employees/items/LeaveLines from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property Employees/items/OpeningBalances/LeaveLines/items/AnnualNumberOfUnits from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property Employees/items/OpeningBalances/LeaveLines/items/CalculationType from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property Employees/items/OpeningBalances/LeaveLines/items/EmploymentTerminationPaymentType from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property Employees/items/OpeningBalances/LeaveLines/items/EntitlementFinalPayPayoutType from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property Employees/items/OpeningBalances/LeaveLines/items/FullTimeNumberOfUnitsPerPeriod from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property Employees/items/OpeningBalances/LeaveLines/items/IncludeSuperannuationGuaranteeContribution from the response with the 200 status

      response-optional-property-removed

    • ○

      added the new optional request property items/PayTemplate/LeaveLines/items/IsQualifyingEarnings

      new-optional-request-property

    • ○

      added the new optional request property items/TaxDeclaration/IncludeLeaveLoadingInQualifyingEarnings

      new-optional-request-property

    • ○

      added the optional property Employees/items/PayTemplate/LeaveLines/items/IsQualifyingEarnings to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property Employees/items/TaxDeclaration/IncludeLeaveLoadingInQualifyingEarnings to the response with the 200 status

      response-optional-property-added

  • 461520d7cf0a44See the full diff
    • ▲

      removed the enum value of the request property items/CountryOfResidence

      request-property-enum-value-removed

    • ▲

      removed the enum value of the request property items/LeaveLines/items/CalculationType

      request-property-enum-value-removed

    • ▲

      removed the enum value of the request property items/OpeningBalances/LeaveLines/items/CalculationType

      request-property-enum-value-removed

    • ▲

      removed the enum value of the request property items/PayTemplate/LeaveLines/items/CalculationType

      request-property-enum-value-removed

    • ○

      removed the enum value from the Employees/items/CountryOfResidence response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the enum value from the Employees/items/LeaveLines/items/CalculationType response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the enum value from the Employees/items/OpeningBalances/LeaveLines/items/CalculationType response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the enum value from the Employees/items/PayTemplate/LeaveLines/items/CalculationType response property for the response status 200

      response-property-enum-value-removed