Xero: Searches payroll employees

← Payroll au operations · Get started

Operation xero.payroll_au_getemployees

Provider route: GET /payroll.xro/1.0/Employees. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/xero with npm, or alter-sdk-xero with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { XeroIntegration } from "@alter-ai/xero";

async function execute(input: Parameters<XeroIntegration["payrollAu"]["getEmployees"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new XeroIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.payrollAu.getEmployees(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_xero import XeroIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = XeroIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.payroll_au.get_employees(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.where	string	Optional
query.order	string	Optional
query.page	integer	Optional
headers	object	Required within parent	Additional keys: not allowed
headers.xero-tenant-id	string	Required within parent
headers.If-Modified-Since	string	Optional	Format: date-time

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Creates a payroll employee — response body

Referenced models: Creates a payroll employee — response body

Schemas

12 more schemas are linked from the tables above, on the schema pages.

Creates a payroll employee — response body

Field	Type	Presence	Description and constraints
$	object	Root
Employees	array	Optional
Employees[]	Model	Each item	Expand Creates a payroll employee — response body — Employees item

Referenced models: Creates a payroll employee — response body — Employees item

Creates a payroll employee — response body — Employees item

Field	Type	Presence	Description and constraints
$	object	Root
BankAccounts	array	Optional
BankAccounts[]	Model	Each item	Expand Creates a payroll employee — response body — Employees item Bank Accounts item
Classification	string	Optional	Employees classification
CountryOfResidence	Model	Optional	Expand Creates a payroll employee — response body — Employees item Country Of Residence
DateOfBirth	string	Required within parent	Date of birth of the employee (YYYY-MM-DD)
Email	string	Optional	The email address for the employee
EmployeeGroupName	string	Optional	The Employee Group allows you to report on payroll expenses and liabilities for each group of employees
EmployeeID	string	Optional	Xero unique identifier for an Employee Format: uuid
EmploymentType	string	Optional	Known values: EMPLOYEE, CONTRACTOR
FirstName	string	Required within parent	First name of employee
Gender	string	Optional	The employee’s gender. See Employee Gender Known values: N, M, F, I
HomeAddress	Model	Optional	Expand Creates a payroll employee — response body — Employees item Home Address
IncomeType	string	Optional	Known values: SALARYANDWAGES, WORKINGHOLIDAYMAKER, NONEMPLOYEE, CLOSELYHELDPAYEES, LABOURHIRE
IsAuthorisedToApproveLeave	boolean	Optional	Authorised to approve other employees' leave requests
IsAuthorisedToApproveTimesheets	boolean	Optional	Authorised to approve timesheets
IsSTP2Qualified	boolean	Optional	Indicates if the employee has been updated for STP Phase 2 compliance. Doesn't indicate that the employee is payable.
JobTitle	string	Optional	JobTitle of the employee
LastName	string	Required within parent	Last name of employee
LeaveBalances	array	Optional
LeaveBalances[]	Model	Each item	Expand Creates a payroll employee — response body — Employees item Leave Balances item
MiddleNames	string	Optional	Middle name(s) of the employee
Mobile	string	Optional	Employee mobile number
OpeningBalances	Model	Optional	Expand Creates a payroll employee — response body — Employees item Opening Balances
OrdinaryEarningsRateID	string	Optional	Xero unique identifier for earnings rate Format: uuid
PayTemplate	Model	Optional	Expand Creates a payroll employee — response body — Employees item Pay Template
PayrollCalendarID	string	Optional	Xero unique identifier for payroll calendar for the employee Format: uuid
Phone	string	Optional	Employee phone number
StartDate	string	Optional	Start date for an employee (YYYY-MM-DD)
Status	string	Optional	Employee Status Types Known values: ACTIVE, TERMINATED
SuperMemberships	array	Optional
SuperMemberships[]	Model	Each item	Expand Creates a payroll employee — request body — body item Super Memberships item
TaxDeclaration	Model	Optional	Expand Creates a payroll employee — response body — Employees item Tax Declaration
TerminationDate	string	Optional	Employee Termination Date (YYYY-MM-DD)
TerminationReason	string	Optional	* `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. Known values: V, I, D, R, F, C, T
Title	string	Optional	Title of the employee
TwitterUserName	string	Optional	Employee’s twitter name
UpdatedDateUTC	string	Optional	Last modified timestamp Read only: true
ValidationErrors	array	Optional	Displays array of validation error messages from the API
ValidationErrors[]	Model	Each item	Expand Retrieves journals — response body — Warnings item

Referenced models: Creates a payroll employee — response body — Employees item Bank Accounts item, Creates a payroll employee — response body — Employees item Country Of Residence, Creates a payroll employee — response body — Employees item Home Address, Creates a payroll employee — response body — Employees item Leave Balances item, Creates a payroll employee — response body — Employees item Opening Balances, Creates a payroll employee — response body — Employees item Pay Template, Creates a payroll employee — request body — body item Super Memberships item, Creates a payroll employee — response body — Employees item Tax Declaration, Retrieves journals — response body — Warnings item

Creates a payroll employee — response body — Employees item Bank Accounts item

Field	Type	Presence	Description and constraints
$	object	Root
AccountName	string	Optional	The name of the account
AccountNumber	string	Optional	The account number
Amount	JSON	Optional
Amount (anyOf 1)	number	Alternative	Fixed amounts (for example, if an employee wants to have $100 of their salary transferred to one account, and the remaining amount to another) Format: double
Amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
BSB	string	Optional	The BSB number of the account
Remainder	boolean	Optional	If this account is the Remaining bank account
StatementText	string	Optional	The text that will appear on your employee's bank statement when they receive payment

Creates a payroll employee — response body — Employees item Country Of Residence

Field	Type	Presence	Description and constraints
$	string	Root	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. Known values: 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

Creates a payroll employee — response body — Employees item Home Address

Field	Type	Presence	Description and constraints
$	object	Root
AddressLine1	string	Required within parent	Address line 1 for employee home address
AddressLine2	string	Optional	Address line 2 for employee home address
City	string	Optional	Suburb for employee home address
Country	string	Optional	Country of HomeAddress
PostalCode	string	Optional	PostCode for employee home address
Region	string	Optional	State abbreviation for employee home address Known values: ACT, NSW, NT, QLD, SA, TAS, VIC, WA

Creates a payroll employee — response body — Employees item Leave Balances item

Field	Type	Presence	Description and constraints
$	object	Root
LeaveName	string	Optional	The name of the leave type
LeaveTypeID	string	Optional	Identifier of the leave type (see PayItems)
NumberOfUnits	JSON	Optional
NumberOfUnits (anyOf 1)	number	Alternative	The balance of the leave available Format: double
NumberOfUnits (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
TypeOfUnits	string	Optional	The type of units as specified by the LeaveType (see PayItems)

Policy, approvals and errors

SDK function policy ID: xero.payroll_au_getemployees. Catalog operation: payroll_au.getEmployees. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source