caret

Employees

Overview

URL https://api.xero.com/payroll.xro/1.0/Employees
Methods Supported POST, GET
Description Allows you to retrieve, add and update payroll employees in a Xero organisation
 

GET Employees

By default using GET Employees will return a summarised list of active employees.

Elements for Employees

FirstName First name of employee
LastName Last name of employee
DateOfBirth Date of birth of the employee (YYYY-MM-DD)
HomeAddress Employee home address. See HomeAddress
StartDate Start date for an employee (YYYY-MM-DD)
Title Title of the employee
MiddleNames Middle name(s) of the employee
Email The email address for the employee
Gender The employee’s gender. See Employee Gender
Phone Employee phone number
Mobile Employee mobile number
TwitterUserName Employee’s twitter name
IsAuthorisedToApproveLeave Authorised to approve other employees' leave requests
IsAuthorisedToApproveTimesheets Authorised to approve timesheets
JobTitle JobTitle of the employee
Classification Employees classification
OrdinaryEarningsRateID Xero unique identifier for earnings rate
PayrollCalendarID Xero unique identifier for payroll calendar for the employee
EmployeeGroupName The Employee Group allows you to report on payroll expenses and liabilities for each group of employees
BankAccounts See BankAccount
PayTemplate See PayTemplate
OpeningBalances See OpeningBalances
LeaveBalances See LeaveBalances
SuperMemberships See SuperMemberships
TerminationDate Employee Termination Date (YYYY-MM-DD)
EmployeeID Xero unique identifier for an Employee
Status See Employee Status Types
UpdatedDateUTC Last modified timestamp

Elements for a HomeAddress

AddressLine1 Address line 1 for employee home address
AddressLine2 Address line 2 for employee home address
City Suburb for employee home address
Region State abbreviation for employee home address
PostalCode PostCode for employee home address
Country Country of HomeAddress

Elements for TaxDeclaration

EmployeeIDXero employee identifier. e.g c56b19ef-75bf-45e8-98a4-e699a96609f7
EmploymentBasisSee Employment Basis Types
TFNExemptionTypeSee TFN Exemption Types
TaxFileNumberThe tax file number e.g ######123.*
AustralianResidentForTaxPurposesIf the employee is Australian resident for tax purposes.(No longer displayed in the UI.)
ResidencyStatusResidency status for tax purposes. See Australian Residency Status.
TaxFreeThresholdClaimedIf tax free threshold claimed.
TaxOffsetEstimatedAmountIf has tax offset estimated then the tax offset estimated amount. e.g 100
HasHELPDebtIf employee has HECS or HELP debt.
HasSFSSDebtIf employee has financial supplement debt.
HasTradeSupportLoanDebtIf employee has trade support loan.
UpwardVariationTaxWithholdingAmountIf the employee has requested that additional tax be withheld each pay run. e.g 50
EligibleToReceiveLeaveLoadingIf the employee is eligible to receive an additional percentage on top of ordinary earnings when they take leave (typically 17.5%). e.g true or false
ApprovedWithholdingVariationPercentageIf the employee has approved withholding variation. e.g (0 - 100)
* As of 1 February 2018 we will no longer be returning the full TFN when accessing the employees end-point via Xero’s Australian Payroll API. The last three digits will still remain visible.

Elements for a BankAccount

StatementText The text that will appear on your employee's bank statement when they receive payment
AccountName The name of the account
BSB The BSB number of the account
AccountNumber The account number
Remainder If this account is the Remaining bank account
Amount Fixed amounts (for example, if an employee wants to have $100 of their salary transferred to one account, and the remaining amount to another)

Elements for a PayTemplate

EarningsLines The earnings rate lines
DeductionLines The deduction type lines
SuperLines The superannuation fund lines
ReimbursementLines The reimbursement type lines
LeaveLines The leave type lines
PayTemplate EarningsLine element
EarningsRateID Xero earnings rate identifier
CalculationType See Earnings Rate Calculation Type
NumberOfUnitsPerWeek Hours per week for the EarningsLine. Applicable for ANNUALSALARY CalculationType
AnnualSalary Annual Salary of employee
RatePerUnit Rate per unit of the EarningsLine.
NormalNumberOfUnits Normal number of units for EarningsLine. Applicable when RateType is "MULTIPLE"
PayTemplate DeductionLine element
DeductionTypeID Xero deduction type identifier
CalculationType See Deduction Type Calculation Type
Percentage The percentage of deduction line
Amount The deduction amount
PayTemplate SuperLine
SuperMembershipID Xero superannuation fund membership identifier
ContributionType See Superannuation Contribution Type
CalculationType See Superannuation Calculation Type
ExpenseAccountCode  Account code for the Expense Account. i.e 478
LiabilityAccountCode  Account code for the Liability Account. i.e 826
MinimumMonthlyEarnings Minimum monthly earnings. Applies for Percentage of Earnings calculation type only
Percentage The percentage of the SuperLine. Applies on Percentage of Earnings CalculationType.
PayTemplate ReimbursementLine
ReimbursementTypeID Xero reimbursement type identifier
Description The description of the reimbursement type
Amount The amount of the reimbursement type
PayTemplate LeaveLine
LeaveTypeID Xero leave type identifier.
CalculationType See Leave Type Calculation Types
AnnualNumberOfUnits Hours of leave accrued each year
FullTimeNumberOfUnitsPerPeriod Normal ordinary earnings number of units for leave line.
NumberOfUnits Number of units for leave line.
EntitlementFinalPayPayoutType See Final Pay Payout Types If you do not provide any value then by Default it will be NOTPAIDOUT.
EmploymentTerminationPaymentType See EmploymentTerminationPaymentType. Pay out leave balance when payee is terminated as Employment Termination Payment (ETP). Optional, can be included only if EntitlementFinalPayPayoutType is PAIDOUT. EmploymentTerminationPaymentType must be O.
IncludeSuperannuationGuaranteeContribution Optional, can be included only if EmploymentTerminationPaymentType is included. Indicate if ETP leave earnings are subject to SGC. Default is false.

Elements for OpeningBalances

OpeningBalanceDate Opening Balance Date. (YYYY-MM-DD)
Tax Opening Balance tax
EarningsLines The EarningsLines of the OpeningBalance.
DeductionLines The DeductionLines of the OpeningBalance.
SuperLines The SuperLines of the OpeningBalance.
ReimbursementLines The ReimbursementLines of the OpeningBalance.
LeaveLines The LeaveLines of the OpeningBalance.
Opening Balance EarningsLine
EarningsRateID Xero earnings rate identifier
Amount Earnings rate amount
Opening Balance DeductionLine
DeductionTypeID Xero deduction type identifier
Amount Deduction type amount
Opening Balance SuperLine
SuperMembershipID Xero super membership ID
CalculationType Calculation type for Super line
Amount Super membership amount
Opening Balance ReimbursementLine
ReimbursementTypeID Xero reimbursement type identifier
Amount Reimbursement type amount
Opening Balance LeaveLine
LeaveTypeID Xero leave type identifier
NumberOfUnits Leave number of units
Elements for LeaveBalances
LeaveName The name of the leave type
LeaveTypeID Identifier of the leave type (see PayItems)
NumberOfUnits The balance of the leave available
TypeOfUnits The type of units as specified by the LeaveType (see PayItems)
Elements for a SuperMembership
SuperFundID Xero identifier for super fund
EmployeeNumber The membership number assigned to the employee by the super fund.
The following are required when updating a SuperMembership
SuperMembershipID Xero unique identifier for Super membership

Example response for GET Employees - 200 OK Response

GET https://api.xero.com/payroll.xro/1.0/Employees

Optional parameters for GET Employees

Record filter You can specify an individual record by appending the value to the endpoint, i.e. GET https://.../Employees/{identifier} This will return all employee information as well as employee’s Bank Account, Opening Balance, Pay Template and super membership
EmployeeID The Xero identifier for an employee e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
Modified After The ModifiedAfter filter is actually an HTTP header: 'If-Modified-Since'. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only employees created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00
page By default the number of records returned per call is 100. You can add GET https://…/Employees?page=2 to get the next set of records.
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)

Example response for GET Employees/{identifier}

GET https://api.xero.com/payroll.xro/1.0/Employees/fb4ebd68-6568-41eb-96ab-628a0f54b4b8

Example of retrieving terminated employees

Using a where filter you can specify a status of TERMINATED. e.g. Status=="TERMINATED"

This translates to the following URL once percent encoded:
https://api.xero.com/payroll.xro/1.0/Employees?where=Status%3D%3D%22TERMINATED%22



  

POST Employees

Use this method to create, update or delete one or more payroll employee items.

Elements for Employees

The following elements are required to create a new employee
FirstName First name of employee (max length = 35)
LastName Last name of employee (max length = 35)
DateOfBirth Date of birth of the employee (YYYY-MM-DD)
HomeAddress Employee home address. See HomeAddress
The following elements are optional when creating a new employee
StartDate If you aren't sure of the exact start date for an employee, you can just enter the start of the current financial year (YYYY-MM-DD)
Title Title of the employee (max length = 10)
MiddleNames Middle name(s) of the employee (max length = 35)
Email The email address for the employee (max length = 100)
Gender The employee’s gender (M or F)
Phone Employee phone number (max length = 50)
Mobile Employee mobile number (max length = 50)
TwitterUserName Employee’s twitter name, entered as @twittername (max length = 50)
IsAuthorisedToApproveLeave Boolean (true / false) - set this to true if the employee is authorised to approve other employees' leave requests
IsAuthorisedToApproveTimesheets Booelan - set this to true if the employee is authorised to approve timesheets
JobTitle JobTitle of the employee (max length = 100)
Classification Employees under an award scheme will be covered by a modern award classification. If you record a classification, it will be included on your payslips (max length = 100)
OrdinaryEarningsRateID Xero unique identifier for earnings rate
PayrollCalendarID Xero unique identifier for payroll calendar for the employee
EmployeeGroupName The Employee Group allows you to report on payroll expenses and liabilities for each group of employees
BankAccounts See BankAccount
PayTemplate See PayTemplate
OpeningBalances See OpeningBalances
LeaveBalances See LeaveBalances
SuperMemberships See SuperMemberships
TerminationDate Employee Termination Date (YYYY-MM-DD)
Other elements
EmployeeID Xero unique identifier for an Employee
Status See Employee Status Types
UpdatedDateUTC Last modified timestamp

Elements for a HomeAddress

AddressLine1 Address line 1 for employee home address (max length = 50)
AddressLine2 Address line 2 for employee home address (max length = 50)
City Suburb for employee home address (max length = 50)
Region State abbreviation for employee home address
PostalCode PostCode for employee home address (max length = 4)
Country Country of HomeAddress

Elements for TaxDeclaration

The following are required to update a tax declaration
EmployeeIDXero employee identifier. e.g c56b19ef-75bf-45e8-98a4-e699a96609f7
EmploymentBasisSee Employment Basis Types
The following are optional to add a tax declaration
TFNExemptionTypeSee TFN Exemption Types
TaxFileNumberThe tax file number e.g 123123123.
AustralianResidentForTaxPurposesIf the employee is Australian resident for tax purposes. e.g true or false
ResidencyStatusSee Australian Residency Status.
TaxFreeThresholdClaimedIf tax free threshold claimed. e.g true or false
TaxOffsetEstimatedAmountIf has tax offset estimated then the tax offset estimated amount. e.g 100
HasHELPDebtIf employee has HECS or HELP debt. e.g true or false
HasSFSSDebtIf employee has financial supplement debt. e.g true or false
HasTradeSupportLoanDebtIf employee has trade support loan. e.g true or false
UpwardVariationTaxWithholdingAmountIf the employee has requested that additional tax be withheld each pay run. e.g 50
EligibleToReceiveLeaveLoadingIf the employee is eligible to receive an additional percentage on top of ordinary earnings when they take leave (typically 17.5%). e.g true or false
ApprovedWithholdingVariationPercentageIf the employee has approved withholding variation. e.g (0 - 100)

Elements for a BankAccount

StatementText The text that will appear on your employee's bank statement when they receive payment (max length = 18)
AccountName The name of the account (max length = 32)
BSB The BSB number of the account (length = 6)
The account number (max length = 9)
Remainder If this account is the Remaining bank account
Amount Fixed amounts (for example, if an employee wants to have $100 of their salary transferred to one account, and the remaining amount to another)

Elements for a PayTemplate

EarningsLines The earnings rate lines
DeductionLines The deduction type lines
SuperLines The superannuation fund lines
ReimbursementLines The reimbursement type lines
LeaveLines The leave type lines
The following are required to add a PayTemplate EarningsLine element
EarningsRateID Xero earnings rate identifier
CalculationType See Earnings Rate Calculation Type
The following elements are optional when adding a PayTemplate EarningsLine element
NumberOfUnitsPerWeek Hours per week for the EarningsLine. Applicable for ANNUALSALARY CalculationType
AnnualSalary Annual Salary of employee
RatePerUnit Rate per unit of the EarningsLine.
NormalNumberOfUnits Normal number of units for EarningsLine. Applicable when RateType is "MULTIPLE"
The following are required to add a PayTemplate DeductionLine element
DeductionTypeID Xero deduction type identifier
CalculationType See Deduction Type Calculation Type
The following elements are optional when adding a PayTemplate DeductionLine
Percentage The percentage of deduction line
Amount The deduction amount
The following are required to add a PayTemplate SuperLine
SuperMembershipID Xero superannuation fund membership identifier
ContributionType See Superannuation Contribution Type
CalculationType See Superannuation Calculation Type
ExpenseAccountCode  Account code for the Expense Account. i.e 478
LiabilityAccountCode  Account code for the Liability Account. i.e 826
The following elements are optional when adding a PayTemplate SuperLine
MinimumMonthlyEarnings Minimum monthly earnings. Applies for Percentage of Earnings calculation type only
Percentage The percentage of the SuperLine. Applies on Percentage of Earnings CalculationType.
The following are required to add a PayTemplate ReimbursementLine
ReimbursementTypeID Xero reimbursement type identifier
The following are optional when adding a PayTemplate ReimbursementLine
Description The description of the reimbursement type
Amount The amount of the reimbursement type
The following are required when adding a PayTemplate LeaveLine
LeaveTypeID Xero leave type identifier.
CalculationType See Leave Type Calculation Types
The following are optional when adding a PayTemplate LeaveLine
AnnualNumberOfUnits Hours of leave accrued each year
FullTimeNumberOfUnitsPerPeriod Normal ordinary earnings number of units for leave line.
NumberOfUnits Number of units for leave line.
EntitlementFinalPayPayoutType See Final Pay Payout Types If you do not provide any value then by Default it will be NOTPAIDOUT.

Elements for OpeningBalances

OpeningBalanceDate Opening Balance Date. (YYYY-MM-DD)
Tax Opening Balance tax
EarningsLines The EarningsLines of the OpeningBalance.
DeductionLines The DeductionLines of the OpeningBalance.
SuperLines The SuperLines of the OpeningBalance.
ReimbursementLines The ReimbursementLines of the OpeningBalance.
LeaveLines The LeaveLines of the OpeningBalance.
The following are required to add an Opening Balance EarningsLine
EarningsRateID Xero earnings rate identifier
Amount Earnings rate amount
The following are required to add an Opening Balance DeductionLine
DeductionTypeID Xero deduction type identifier
Amount Deduction type amount
The following are required to add an Opening Balance SuperLine
SuperMembershipID Xero super membership ID
CalculationType Calculation type for Super line
Amount Super membership amount
The following are required to add an Opening Balance ReimbursementLine
ReimbursementTypeID Xero reimbursement type identifier
Amount Reimbursement type amount
The following are required to add an Opening Balance LeaveLine
LeaveTypeID Xero leave type identifier
NumberOfUnits Leave number of units
Elements for LeaveBalances
LeaveName The name of the leave type
LeaveTypeID Identifier of the leave type (see PayItems)
NumberOfUnits The balance of the leave available
TypeOfUnits The type of units as specified by the LeaveType (see PayItems)
Elements for a SuperMembership
SuperFundID Xero identifier for super fund
EmployeeNumber The membership number assigned to the employee by the super fund.
The following are required when updating a SuperMembership
SuperMembershipID Xero unique identifier for Super membership

Example of minimum elements required to add a new Employee

POST https://api.xero.com/payroll.xro/1.0/Employees/

An example showing an employee's details being updated

POST https://api.xero.com/payroll.xro/1.0/Employees/


  

An example showing creating an employee with an opening balance

POST https://api.xero.com/payroll.xro/1.0/Employees/