Xero Payroll API


Overview

Current Version : v1.6.0
Last Updated : August 11, 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.

There is a separate API Reference for each region (AU and US) as there are subtle terminology and functionality differences in each region.

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 :


Getting started

Organizations (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 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)

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

&scope=payroll.employees,payroll.timesheets,payroll.settings, payroll.payitems,payroll.payruns,payroll.payschedules,
payroll.worklocations

payroll-auth
Once connected you can find the Payroll API endpoints at the bottom of the Endpoints dropdown list.