Xero Payroll API
Current Version : v1.2
Last Updated : 12 September, 2013 (release notes)
The Xero 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 the payroll Xero application 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 :
- The Xero Payroll API is currently available for use with Australian organisations only.
- Australian Xero organisations (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 endpoints have paginating results (note this differs from the existing v2 Xero API)
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 needs to be authorised with sufficient privileges to allow use with the Payroll API. Once connected you can find the Payroll API endpoints at the bottom of the Endpoints dropdown list.