Join us at Xero Developer Roadshow, June 2018 at a city near you. Register Free

Employees

This endpoint is used for an employee type used exclusively by the global Payrun functionality in Xero core accounting. This is NOT the endpoint to use for Xero's regional Payroll employee types. Different endpoints are used for employees in the US and Australian Payroll API. UK and NZ Payroll APIs are currently in beta.

If you are trying to represent employees in Xero for the purposes of allowing the payment of bills to employees (i.e. reimbursing for expenses) please see the contacts endpoint and use the "IsSupplier" flag to enable payment of bills to this contact. You can also create a contact group called "employees" if you so choose.

Overview

URL https://api.xero.com/api.xro/2.0/Employees
Methods Supported POST, PUT, GET
Description Allows you to retrieve, add and update employees used in Xero payrun functionality

GET Employees

User this method to retrieve one or many employees

EmployeeID Xero identifier
Status Current status of an employee - see contact status types
FirstName First name of an employee
LastName Last name of an employee
External Link Link to an external resource, for example, an employee record in an external system. You can specify the URL element.
The description of the link is auto-generated in the form "Go to <App name>". <App name> refers to the Xero application name that is making the API call.

Optional parameters for GET Employees

Record filter You can specify an individual record by appending the EmployeeID to the endpoint, i.e. GET https://.../Employees/{EmployeeID}
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
Where Filter by an any element ( see Filters )
order Order by any element returned ( see Order By )

Example response for retrieving Employees

GET https://api.xero.com/api.xro/2.0/Employees

POST Employees

Use this method to create or update one or more employee records.

Status Current status of an employee - see contact status types
FirstName First name of an employee (max length = 255)
LastName Last name of an employee (max length = 255)
External Link Link to an external resource, for example, an employee record in an external system. You can specify the URL element.
The description of the link is auto-generated in the form "Go to <App name>". <App name> refers to the Xero application name that is making the API call.

When you are updating an employee you don’t need to specify every element. If you exclude an element then the existing value of that field will be preserved.

PUT Employees

Use this method to create one or more employee records. This method works very similar to POST Employees but if an existing employee matches your FirstName and LastName then you will receive an error.

Example of minimum elements required to add a new employee

POST https://api.xero.com/api.xro/2.0/Employees

Example of the full set of elements you can specify for an employee

POST https://api.xero.com/api.xro/2.0/Employees

Example of minimum elements required to add many employees

POST https://api.xero.com/api.xro/2.0/Employees