Employees


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 in a Xero organisation

XML Elements for employees

EmployeeID Xero identifier
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.

POST Employees

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

Example of minimum elements required to add a new employee

<Employee>
  <FirstName>John</FirstName>
  <LastName>Smith</LastName>
</Employee>

Example of maximum elements you can specify for an employee

<Employee>
  <FirstName>John</FirstName>
  <LastName>Smith</LastName>
    <ExternalLink>
        <Url>http://twitter.com/#!/search/Joe+Bloggs</Url>
    </ExternalLink>
</Employee>

Example of minimum elements required to add many employees

<Employees>
  <Employee>
    <FirstName>John</FirstName>
    <LastName>Smith</LastName>
  </Employee>
  <Employee>
    <FirstName>Rachel</FirstName>
    <LastName>Redman</LastName>
  </Employee>
</Employees>

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.


GET 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}
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
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)

Example response for GET Employees

<Employee>
      <EmployeeID>514ad9aa-8e4b-4a0a-859a-9f72658eeadc</EmployeeID>
      <Status>ACTIVE</Status>
      <FirstName>Homer</FirstName>
      <LastName>Simpson</LastName>
      <ExternalLink>
        <Url>http://twitter.com/#!/search/Homer+Simpson</Url>
        <Description>Go to Twitter</Description>
      </ExternalLink>
</Employee>