Employees

Allows you to query, insert, and update employee records. Employees are individuals working for the organization, and their data includes payroll, tax, and employment information.

Table Specific Information

The Employees table allows you to SELECT and INSERT Payroll employees for a Xero organization.

SELECT

The Xero API allows extensive filtering and ordering. You can define WHERE and ORDER BY clauses in a query to filter and order the results using any non-line-item column.

Note: The Xero API does not support filtering on line items or journal lines.

INSERT

To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new Employee, the FirstName, LastName, Status, Title, DateOfBirth, JobTitle, HomeAddress_AddressLine1, HomeAddress_City, HomeAddress_Region, HomeAddress_PostalCode, and HomeAddress_Country are required.

INSERT INTO Employees (FirstName, LastName, Status, Title, DateOfBirth, JobTitle, HomeAddress_AddressLine1, HomeAddress_City, HomeAddress_Region, HomeAddress_PostalCode, HomeAddress_Country) VALUES ('John', 'Doe', 'ACTIVE', 'Mr', '1986-01-01', 'Engineer', '123 Hollywood Dr', 'Sydney', 'ACT', '3000', 'Australia')

Employees can also be added in bulk by specifying multiple records in the VALUES clause.

INSERT INTO Employees (FirstName, LastName, Status, Title, DateOfBirth, JobTitle, HomeAddress_AddressLine1, HomeAddress_City, HomeAddress_Region, HomeAddress_PostalCode, HomeAddress_Country) 
	VALUES 
	('John', 'Doe', 'ACTIVE', 'Mr', '1986-01-01', 'Engineer', '123 Hollywood Dr', 'Sydney', 'ACT', '3000', 'Australia'),
	('Jane', 'Doe', 'ACTIVE', 'Mr', '1986-01-01', 'Engineer', '123 Hollywood Dr', 'Sydney', 'ACT', '3000', 'Australia')

UPDATE

You can update any field that is not read-only.

Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.

DELETE

The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.

Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.

Columns


Name	Type	ReadOnly	Filterable	Description
EmployeeID [KEY]	String	True		The unique identifier of the employee. This field is assigned by Xero.
Status	String	False		The status of the employee. Valid values are 'ACTIVE' and 'TERMINATED'.
Title	String	False		The title of the employee.
FirstName	String	False		The first name of the employee.
MiddleNames	String	False		The middle names of the employee.
LastName	String	False		The last name of the employee.
DateOfBirth	Date	False		The employee's birthday.
Gender	String	False		The gender of the employee.
Phone	String	False		The employee's home phone number.
Mobile	String	False		The employee's mobile phone number.
Email	String	False		The employee's email address.
CountryOfResidence	String	False		The country of residence for the employee.
TwitterUserName	String	False		The employee's Twitter (X) username.
IsSTP2Qualified	Boolean	False		Indicates whether the employee meets the criteria to be reported under Single Touch Payroll Phase 2 (STP2).
JobTitle	String	False		The job title of the employee.
EmploymentType	String	False		The type of employment for the employee, such as 'FULLTIME', 'PARTTIME', or 'CASUAL'.
IncomeType	String	False		The income type of the employee for STP2 reporting purposes, such as 'SALARYANDWAGES' or 'CLOSELYHELDPAYEES'.
Classification	String	False		The employee's job classification or position category within the organisation.
StartDate	Date	False		The employee's hire date.
TerminationDate	Date	False		The employee's termination date.
TerminationReason	String	False		The reason for the employee's termination, as a one-letter code.
OrdinaryEarningsRateID	String	False		A reference to the employee's earnings rate.
PayrollCalendarID	String	False		A reference to the employee's pay schedule.
IsAuthorisedToApproveLeave	Boolean	False		Indicates whether the employee is authorized to approve time off.
IsAuthorisedToApproveTimesheets	Boolean	False		Indicates whether the employee is authorized to approve timesheets.
EmployeeGroupName	String	False		The name of the tracking category the employee belongs to, if one is assigned.
UpdatedDateUTC	Datetime	True		Timestamp of the last change to the employee record.
HomeAddress_AddressLine1	String	False		Address Line 1 for employee home address.
HomeAddress_AddressLine2	String	False		Address Line 2 for employee home address.
HomeAddress_City	String	False		Suburb for employee home address.
HomeAddress_Region	String	False		State abbreviation for employee home address.
HomeAddress_PostalCode	String	False		Postal code for employee home address.
HomeAddress_Country	String	False		Country of the employee's home address.
TaxDeclaration_EmploymentBasis	String	False		The employment basis for tax purposes. Options include 'FULLTIME', 'PARTTIME', 'CASUAL', 'LABOURHIRE', or 'SUPERINCOMESTREAM'.
TaxDeclaration_TFNExemptionType	String	False		If the employee has no Tax File Number (TFN), use one of the following options: 'NOTQUOTED', 'PENDING', 'PENSIONER', or 'UNDER18'.
TaxDeclaration_TaxFileNumber	String	False		The last three digits of the employee's TFN.
TaxDeclaration_AustralianResidentForTaxPurposes	Boolean	False		Indicates whether the employee is an Australian resident for tax purposes.
TaxDeclaration_ResidencyStatus	String	False		The residency status of the employee. Options include 'AUSTRALIANRESIDENT', 'FOREIGNRESIDENT', or 'WORKINGHOLIDAYMAKER'.
TaxDeclaration_TaxFreeThresholdClaimed	Boolean	False		Indicates whether the employee claims to make below the tax-free threshold.
TaxDeclaration_UpwardVariationTaxWithholdingAmount	Decimal	False		The extra withholding the employee has requested, in percent.
TaxDeclaration_EligibleToReceiveLeaveLoading	Boolean	False		If the employee is eligible to receive extra earnings when they take leave.
TaxDeclaration_IncludeLeaveLoadingInQualifyingEarnings	Boolean	False		Indicates whether leave loading is included in the qualifying earnings calculation for superannuation guarantee purposes.
TaxDeclaration_ApprovedWithholdingVariationPercentage	Decimal	False		The extra withholding the employee has been granted, in percent.
TaxDeclaration_SeniorMaritalStatus	String	False		The marital status declared by the employee.
TaxDeclaration_TaxOffsetEstimatedAmount	Decimal	False		Any other tax offsets the employee has claimed.
TaxDeclaration_ABN	String	False		The Australian Business Number (ABN) provided by the employee on their tax declaration.
TaxDeclaration_TaxScaleType	String	False		The tax scale type from the employee's tax declaration, which determines how PAYG withholding tax is calculated.
TaxDeclaration_WorkCondition	String	False		The work condition specified on the employee's tax declaration, such as whether they are an Australian resident for tax purposes.
TaxDeclaration_HasHELPDebt	Boolean	False		Indicates whether the employee has Higher Education Loan Program (HELP) debt.
TaxDeclaration_HasSFSSDebt	Boolean	False		Indicates whether the employee has financial supplement debt.
TaxDeclaration_HasTradeSupportLoanDebt	Boolean	False		Indicates whether the employee has a trade support loan.
TaxDeclaration_HasStudentStartupLoan	Boolean	False		Indicates whether the employee has a Student Start-up Loan that requires additional tax withholding.
TaxDeclaration_HasLoanOrStudentDebt	Boolean	False		Indicates whether the employee has a HECS, HELP, VSL, SSL, ABSTUDY SSL, or TSL debt requiring additional withholding.
BankAccounts	String	True		The bank accounts for the employee in XML format.
PayTemplate	String	True		The pay template for the employee in XML format.
OpeningBalances	String	True		The opening balances for the employee in XML format.
LeaveBalances	String	True		The leave balances for the employee in XML format.
SuperMemberships	String	True		The super memberships for the employee in XML format.
TenantId [KEY]	String	False		The ID of the tenant to query instead of the connection tenant.