Xero Payroll API


Overview

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.

Differences

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 :


Availability

  • 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.

Permissions

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

Authorising access

In order to authorise any API connection the Xero user must have the Standard or Adviser role.

In addition, only Xero users with payroll administrator access can authorise access to payroll endpoints.

Private applications

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.


URLs

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

Versions

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.


Pagination

All payroll endpoints have paginating results (note this differs from the existing v2 Xero API)

Maximum records

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.


API Previewer

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.