Xero Payroll API
Current Version : v1.7.0
Last Updated : December 8, 2014 (release notes)
Payroll in Xero is available in Australia and the US (in a growing number of States)
The Payroll API is a RESTful web service and uses the OAuth (v1.0a) protocol to authenticate 3rd party applications.
The Payroll API exposes payroll related functions of Payroll in Xero and can be used for a variety of purposes such as syncing employee details, importing timesheets etc.
If you are already familiar with the Core API, it is important to review the notes below as there are a number of differences in how the Payroll API behaves including :
Organizations (including the sample Demo company) must have concluded the payroll setup steps before the Payroll API can be used.
By default all API applications have access to the accounting endpoints only.
Requesting access to use payroll endpoints
With public and partner applications you need to specify the “scope” parameter when you redirect the user to the Authorise screen in Xero to request sufficient privileges. Each endpoint specified has the “payroll.” prefix.
e.g. The URL to request access to the use Employees and PayItems endpoints is https://api.xero.com/oauth/Authorize?scope=payroll.employees,payroll.payitems
In addition, only Xero users with payroll administrator access can authorise access to payroll endpoints.
With private applications you can authorise access to the Payroll API when you register your application. There is a checkbox to enable Payroll API access on the Add application screen. Once this is checked your application will have permissions to access to all payroll endpoints.
The base url for all payroll endpoints is https://api.xero.com/payroll.xro/1.0/
e.g. The URL for the Employees endpoint is https://api.xero.com/payroll.xro/1.0/Employees
The Payroll API is currently version 1.0 and may be updated separately to the Core API. Please see the Payroll API release notes for the latest improvements.
All Payroll API endpoints return paginating results on GET requests (note this differs from the Core API where paging is optional and only available on a few endpoints)
A maximum of 100 records will be returned per request. To fetch the second page append a page parameter to the URL e.g. ?page=2. If there are 100 records in the response you will need to check if there is any more data by fetching the next page.
Types and Codes
See the Types and Codes applicable for use with the Payroll API endpoints.
The API Previewer currently does not include Payroll permission scopes to allow use with the Payroll API. You can work around this limitation by appending the “scope” parameter to your authorize URL in the browser address bar. Hit the “enter key” to apply the scope, then click the authorize button.