This endpoint is used for the Payrun functionality in Xero core accounting. This is NOT the endpoint to use for Xero Payroll employees. Different endpoints are used for employees in the US and Australian Payroll API. UK and NZ Payroll APIs are coming soon.
| 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 |
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. |
| 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
<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>
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.
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
<Employee> <FirstName>John</FirstName> <LastName>Smith</LastName> </Employee>
Example of the full set of elements you can specify for an employee
POST https://api.xero.com/api.xro/2.0/Employees
<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
POST https://api.xero.com/api.xro/2.0/Employees
<Employees>
<Employee>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Employee>
<Employee>
<FirstName>Rachel</FirstName>
<LastName>Redman</LastName>
</Employee>
</Employees>