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

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 employee (YYYY-MM-DD)
HomeAddress Employee home address. See HomeAddress
The following elements are optional when creating a new employee
MiddleNames Middle name(s) of the employee (max length = 35)
JobTitle Job Title of the employee
Email Employee email address
Gender Gender of employee (M or F)
MailingAddress See MailingAddress
Phone Phone number of employee
EmployeeNumber Employee Number
SocialSecurityNumber Social Security Number of the employee (xxx-xx-xxxx)
StartDate Start date of employee (YYYY-MM-DD)
PayScheduleID Xero unique identifier – PayScheduleID for the employee
EmployeeGroupName Employee group name
Employment Basis See Employment Basis Types
HolidayGroupID HolidayGroupID of the employee
IsAuthorisedToApproveTimeOff Boolean to specify if employee is authorised to approve time off
IsAuthorisedToApproveTimesheets Boolean to specify if employee is authorised to approve timesheets
SalaryAndWages See SalaryAndWages
WorkLocations See WorkLocations
PaymentMethod See PaymentMethods
PayTemplate See PayTemplate
OpeningBalances See OpeningBalances
Other elements
EmployeeID Xero unique identifier for an Employee
Status See Employee Status Types
UpdatedDateUTC Last modified timestamp

Elements for a HomeAddress or Mailing Address

Street Address Street Address for employee home address
SuiteOrAptOrUnit Suite, Apartment or Unit information for employee home address
City City for employee home address
State State abbreviation for employee home address
Zip Zip (Post code) for employee home address
Lattitude The Latitude of employee home address
Longitude The Longitude of employee home address

Elements for SalaryAndWages

At most two <SalaryAndWage> items can be specified. A SalaryAndWageID will get auto generated on creation
SalaryAndWageID Xero unique identifier for SalaryAndWage item. e.g c56b19ef-75bf-45e8-98a4-e699a96609f7
EarningsTypeID Xero unique identifier for EarningsType item. e.g c56b19ef-75bf-45e8-98a4-e699a96609f7
SalaryWagesType See Salary and Wages Types
HourlyRate The Hourly rate of the Salary and Wages Type. Applies only when SalaryWagesType is HOURLY
AnnualSalary The annual salary for the Salary and wages. Applies only when SalaryWagesType is SALARY
StandardHoursPerWeek Number of hours per week
EffectiveDate The effective date of the Salary and Wages

Elements for WorkLocations

An employee can have one or more <WorkLocation> elements.
WorkLocationID Xero unique identifier for WorkLocation. e.g c56b19ef-75bf-45e8-98a4-e699a96609f7
IsPrimary Boolean to specify if this work location is the primary work location

Elements for a PaymentMethod

PaymentMethodType See PaymentMethodTypes
BankAccounts The Bank accounts for the employee. Only Applies when PaymentMethodType is DIRECTDEPOSIT

Elements for a BankAccount

AccountHolderName The name of bank account holder exactly how the bank has it.
StatementText The text that will appear on your employee’s bank statement when they receive payment
AccountType See Account Types
RoutingNumber Bank routing number is the nine digit number used to identify a financial institution
AccountNumber The account number for the 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)
Remainder Set it to true if this bank account should be the Remainder bank account

Elements for a PayTemplate

EarningsLines The earnings rate lines
DeductionLines The deduction type lines
ReimbursementLines The reimbursement type lines
BenefitLines The benefit type lines

The following are required to add a PayTemplate EarningsLine element

EarningsTypeID Xero earnings rate identifier

The following elements are optional when adding a PayTemplate EarningsLine element

UnitsOrHours The Units or Hours for the earnings line
RatePerUnit Rate per unit for the EarningsLine.
Amount The amount for the earnings line

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

EmployeeMax Maximum amount an employee can receive
Percentage The percentage of deduction line
Amount The deduction amount

The following are required to add a PayTemplate ReimbursementLine

ReimbursementTypeID Xero identifier for reimbursement type

The following elements are optional when adding a PayTemplate ReimbursementLine

Description The description of the reimbursement line
Amount The amount of the reimbursement line

The following are required to add a PayTemplate BenefitLine

BenefitTypeID Xero identifier for benefit type
CalculationType Benefit type calculation type

The following are optional when adding a PayTemplate BenefitLine

Amount The amount of the reimbursement type

Elements for OpeningBalances

EarningsLines The EarningsLines of the OpeningBalance.
BenefitLines The BenefitLines of the OpeningBalance.
DeductionLines The DeductionLines of the OpeningBalance.
ReimbursementLines The ReimbursementLines of the OpeningBalance.

The following are required to add an Opening Balance EarningsLine

EarningsTypeID Xero earnings rate identifier
Amount Earnings rate amount

The following are required to add an Opening Balance BenefitLine

BenefitTypeID Xero benefit type identifier
Amount Benefit type 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 ReimbursementLine

ReimbursementTypeID Xero reimbursement type identifier
Amount Reimbursement type amount

GET Employees

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

Example response for GET Employees

<Employees>
    <Employee>
      <EmployeeID>02bf4d49-14c9-41fc-aeb5-0c7ec2d303c3</EmployeeID>
      <FirstName>Employee</FirstName>
      <LastName>1</LastName>
      <Status>ACTIVE</Status>
      <Email>asdhg@asd.com</Email>
      <DateOfBirth>1980-01-01T00:00:00</DateOfBirth>
      <Gender>M</Gender>
      <Phone>234-234-4234</Phone>
      <StartDate>2014-01-26T00:00:00</StartDate>
      <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
      <UpdatedDateUTC>2014-03-21T01:02:17</UpdatedDateUTC>
    </Employee>
    <Employee>
      <EmployeeID>3dd6b076-9667-4a2c-b9fd-02b8a44be049</EmployeeID>
      <FirstName>Employee</FirstName>
      <LastName>2</LastName>
      <Status>ACTIVE</Status>
      <Email>asdhg@asd.com</Email>
      <DateOfBirth>1980-01-01T00:00:00</DateOfBirth>
      <Gender>M</Gender>
      <Phone>234-234-4234</Phone>
      <StartDate>2014-01-26T00:00:00</StartDate>
      <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
      <UpdatedDateUTC>2014-03-21T01:44:03</UpdatedDateUTC>
    </Employee>
    <Employee>
      <EmployeeID>7b41f995-1b15-48be-ba94-cd2877aaeb75</EmployeeID>
      <FirstName>Employee</FirstName>
      <LastName>3</LastName>
      <Status>ACTIVE</Status>
      <StartDate>2014-02-01T00:00:00</StartDate>
      <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
      <UpdatedDateUTC>2014-02-25T23:12:55</UpdatedDateUTC>
    </Employee>
    <Employee>
      <EmployeeID>b02f94ec-abf1-48d3-adbd-d4ee844f4c11</EmployeeID>
      <FirstName>Employee</FirstName>
      <LastName>4</LastName>
      <Status>ACTIVE</Status>
      <StartDate>2014-02-23T00:00:00</StartDate>
      <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
      <UpdatedDateUTC>2014-03-16T22:11:29</UpdatedDateUTC>
    </Employee>
    <Employee>
      <EmployeeID>5f2f8bb6-bc7c-4227-9310-341394540620</EmployeeID>
      <FirstName>Employee</FirstName>
      <LastName>5</LastName>
      <Status>ACTIVE</Status>
      <Email>paul@xero.com</Email>
      <DateOfBirth>1972-01-07T00:00:00</DateOfBirth>
      <Gender>M</Gender>
      <Phone>415-673-4567</Phone>
      <StartDate>2014-02-01T00:00:00</StartDate>
      <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
      <UpdatedDateUTC>2014-02-13T00:57:33</UpdatedDateUTC>
    </Employee>
  </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 and Pay Template
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}

<Employee>
  <EmployeeID>1f75ea62-54c4-4b68-9808-438787c863d2</EmployeeID>
  <FirstName>Henry</FirstName>
  <LastName>Smith</LastName>
  <JobTitle>Supervisor</JobTitle>
  <Status>ACTIVE</Status>
  <Email>henry@sampleinc.com</Email>
  <DateOfBirth>1979-09-09T00:00:00</DateOfBirth>
  <Gender>M</Gender>
  <HomeAddress>
   <StreetAddress>123 E 16th St</StreetAddress>
   <SuiteOrAptOrUnit>123</SuiteOrAptOrUnit>
   <City>Manhattan</City>
   <State>NY</State>
   <Zip>10003</Zip>
   <Latitude>40.72947</Latitude>
   <Longitude>-73.98553</Longitude>
  </HomeAddress>
  <MailingAddress>
    <StreetAddress>123 E 16th St</StreetAddress>
    <SuiteOrAptOrUnit>123</SuiteOrAptOrUnit>
    <City>Manhattan</City>
    <State>NY</State>
    <Zip>10003</Zip>
    <Latitude>41.72947</Latitude>
    <Longitude>-71.98553</Longitude>
  </MailingAddress>
  <Phone>123-123-1312</Phone>
  <SocialSecurityNumber>***-**-2121</SocialSecurityNumber>
  <StartDate>2014-05-01T00:00:00</StartDate>
  <PayScheduleID>82720152-f125-4bfd-96a5-52267d32f8d0</PayScheduleID>
  <UpdatedDateUTC>2014-06-03T00:27:46</UpdatedDateUTC>
  <SalaryAndWages>
    <SalaryAndWage>
      <SalaryAndWagesID>c62d7448-b040-4a75-87be-0b9eff550359</SalaryAndWagesID>
      <EarningsTypeID>7bd17f4f-7564-4418-88ae-4a870f307ce5</EarningsTypeID>
      <SalaryWagesType>HOURLY</SalaryWagesType><HourlyRate>10.000000</HourlyRate>
      <StandardHoursPerWeek>50.0000</StandardHoursPerWeek>
      <EffectiveDate>2014-06-03T12:00:00</EffectiveDate>
    </SalaryAndWage>
    <SalaryAndWage>
      <SalaryAndWagesID>c12f28b4-6400-4d55-b30b-c5c92a0ea2d3</SalaryAndWagesID>
      <EarningsTypeID>7bd17f4f-7564-4418-88ae-4a870f307ce5</EarningsTypeID>
      <SalaryWagesType>HOURLY</SalaryWagesType>
      <HourlyRate>40.000000</HourlyRate>
      <StandardHoursPerWeek>50.0000</StandardHoursPerWeek>
      <EffectiveDate>2014-08-04T12:00:00</EffectiveDate>
    </SalaryAndWage>
  </SalaryAndWages>
  <WorkLocations>
    <WorkLocation>
      <WorkLocationID>475dd776-09b4-4998-a001-958d0f7a0624</WorkLocationID>
      <IsPrimary>true</IsPrimary>
    </WorkLocation>
  </WorkLocations>
  <PaymentMethod>
    <PaymentMethodType>CHECK</PaymentMethodType>
  </PaymentMethod>
  <PayTemplate>
    <EarningsLines>
      <EarningsLine>
        <EarningsTypeID>9433525e-fc87-41ae-b142-963686f962fd</EarningsTypeID>
        <UnitsOrHours>10.0000</UnitsOrHours>
        <RatePerUnit>15.000000</RatePerUnit>
      </EarningsLine>
    </EarningsLines>
    <DeductionLines/>
    <ReimbursementLines/>
    <BenefitLines/>
  </PayTemplate>
  <OpeningBalances>
    <EarningsLines/>
    <BenefitLines/>
    <DeductionLines/>
    <ReimbursementLines/>
  </OpeningBalances>
</Employee>

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

<Employees>
    <Employee>
        <EmployeeID>d5057392-d676-4d31-8811-5be2edc30e42</EmployeeID>
        <FirstName>Employee FirstName</FirstName>
        <LastName>Employee LastName</LastName>
        <Status>TERMINATED</Status>
        <StartDate>2013-01-07T00:00:00</StartDate>
        <TerminationDate>2013-03-06T00:00:00</TerminationDate>
        <UpdatedDateUTC>2013-02-28T00:23:36</UpdatedDateUTC>
    </Employee>
</Employees>

POST Employees

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

Example of minimum elements required to add a new Employee

<Employees>
  <Employee>
    <FirstName>MyFirstName</FirstName>
    <LastName>MyLastName</LastName>
    <HomeAddress>
      <StreetAddress>244 Jackson St</StreetAddress>
      <City>San Francisco</City>
      <State>CA</State>
      <Zip>94111</Zip>
      <Latitude>37.79690</Latitude>
      <Longitude>-122.40033</Longitude>
    </HomeAddress>
  </Employee>
</Employees>

An example showing an employees details being updated

<Employees>
  <Employee>
    <FirstName>MyFirstName</FirstName>
    <LastName>MyLastName</LastName>
    <JobTitle>Marketing Manager</JobTitle>
    <Status>ACTIVE</Status>
    <Email>email@eamil.com</Email>
    <DateOfBirth>1980-01-01T00:00:00</DateOfBirth>
    <Gender>M</Gender>
    <HomeAddress>
      <StreetAddress>244 Jackson St</StreetAddress>
      <City>San Francisco</City>
      <State>CA</State>
      <Zip>94111</Zip>
      <Latitude>37.79690</Latitude>
      <Longitude>-122.40033</Longitude>
    </HomeAddress>
    <MailingAddress>
      <StreetAddress>244 Jackson St</StreetAddress>
      <City>San Francisco</City>
      <State>CA</State>
      <Zip>94111</Zip>
      <Latitude>37.79690</Latitude>
      <Longitude>-122.40033</Longitude>
    </MailingAddress>
    <Phone>123-123-1231</Phone>
    <SocialSecurityNumber>***-**-4324</SocialSecurityNumber>
    <StartDate>2014-02-01T00:00:00</StartDate>
    <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
    <EmploymentBasis>FULLTIME</EmploymentBasis>
    <HolidayGroupID>05e42562-2d0d-4692-b426-dac12df50d92</HolidayGroupID>
    <UpdatedDateUTC>2014-02-28T04:26:03</UpdatedDateUTC>
    <IsAuthorisedToApproveTimeOff>true</IsAuthorisedToApproveTimeOff>
    <IsAuthorisedToApproveTimesheets>true</IsAuthorisedToApproveTimesheets>
    <SalaryAndWages>
      <SalaryAndWage>
        <EarningsTypeID>5a467a52-e60e-4a3d-bca8-3447a8e1fd79</EarningsTypeID>
        <SalaryWagesType>HOURLY</SalaryWagesType>
        <HourlyRate>40.000000</HourlyRate>
        <StandardHoursPerWeek>40.0000</StandardHoursPerWeek>
      </SalaryAndWage>
    </SalaryAndWages>
    <WorkLocations>
      <WorkLocation>
        <WorkLocationID>adc0dd19-1958-40f7-9cda-82ebf146bbd1</WorkLocationID>
        <IsPrimary>true</IsPrimary>
      </WorkLocation>
    </WorkLocations>
    <PaymentMethod>
      <PaymentMethodType>DIRECTDEPOSIT</PaymentMethodType>
      <BankAccounts>
        <BankAccount>
          <AccountHolderName>Account Holder Name 1</AccountHolderName>
          <StatementText>Statement Text 1</StatementText>
          <AccountType>SAVINGS</AccountType>
          <RoutingNumber>291273510</RoutingNumber>
          <AccountNumber>123123123</AccountNumber>
          <Remainder>true</Remainder>
        </BankAccount>
        <BankAccount>
          <AccountHolderName>Account Holder Name 2</AccountHolderName>
          <StatementText>Statement Text 2</StatementText>
          <AccountType>SAVINGS</AccountType>
          <RoutingNumber>291273510</RoutingNumber>
          <AccountNumber>234234234</AccountNumber>
          <Amount>323.00</Amount>
          <Remainder>false</Remainder>
        </BankAccount>
      </BankAccounts>
    </PaymentMethod>
    <PayTemplate>
      <EarningsLines>
        <EarningsLine>
          <EarningsTypeID>5a467a52-e60e-4a3d-bca8-3447a8e1fd79</EarningsTypeID>
          <UnitsOrHours>20.0000</UnitsOrHours>
          <RatePerUnit>24.000000</RatePerUnit>
        </EarningsLine>
      </EarningsLines>
      <DeductionLines>
        <DeductionLine>
          <DeductionTypeID>7bd5f5ac-de4c-4b09-84d0-ad9150a8ab44</DeductionTypeID>
          <CalculationType>FIXEDAMOUNT</CalculationType>
          <Amount>20.00</Amount>
        </DeductionLine>
      </DeductionLines>
      <ReimbursementLines>
        <ReimbursementLine>
          <ReimbursementTypeID>d4cb9570-dbec-49e8-88f1-8c37354fab1d</ReimbursementTypeID>
          <Description>Some Description </Description>
          <Amount>20.00</Amount>
        </ReimbursementLine>
      </ReimbursementLines>
      <BenefitLines>
        <BenefitLine>
          <BenefitTypeID>9fca3a4b-d767-4ba5-952d-36287f98811e</BenefitTypeID>
          <CalculationType>FIXEDAMOUNT</CalculationType>
          <Amount>100.0000</Amount>
        </BenefitLine>
      </BenefitLines>
    </PayTemplate>
    <OpeningBalances>
      <EarningsLines>
        <EarningsLine>
          <EarningsTypeID>5a467a52-e60e-4a3d-bca8-3447a8e1fd79</EarningsTypeID>
          <Amount>10.00</Amount>
        </EarningsLine>
      </EarningsLines>
      <BenefitLines>
        <BenefitLine>
          <BenefitTypeID>9fca3a4b-d767-4ba5-952d-36287f98811e</BenefitTypeID>
          <Amount>20.00</Amount>
        </BenefitLine>
      </BenefitLines>
      <DeductionLines>
        <DeductionLine>
          <DeductionTypeID>7bd5f5ac-de4c-4b09-84d0-ad9150a8ab44</DeductionTypeID>
          <Amount>15.00</Amount>
        </DeductionLine>
      </DeductionLines>
      <ReimbursementLines>
        <ReimbursementLine>
          <ReimbursementTypeID>ca1373ae-0408-4366-bca9-a5bedfb16d6f</ReimbursementTypeID>
          <Amount>25.00</Amount>
        </ReimbursementLine>
      </ReimbursementLines>
    </OpeningBalances>
  </Employee>
</Employees>