Payroll API Reference

Current Version : v1.0 beta
Last Updated : 25 March, 2013 – see release notes

Overview

The Xero Payroll API is currently available for use with Australian organisations only.

The Payroll API follows the same familiar request and response formats as the Xero API v2 and utilises the same app registration and authorisation process

The base url for all payroll endpoints is https://api.xero.com/payroll.xro/1.0/

Endpoints

e.g. The URL for the Employees endpoint is https://api.xero.com/payroll.xro/1.0/Employees

Types and Codes

Learn about the Types and Codes used with the endpoints above

Permissions

  • By default all API applications have access to the accounting endpoints only.
  • To access payroll endpoints you need to use an access token that has the correctly granted permissions. To do this you need to specify the “scope” parameter when you redirect the user to the Authorise screen in Xero. Each endpoint specified has the “payroll.” prefix

    e.g. https://api.xero.com/oauth/Authorize?scope=payroll.employees,payroll.payitems

    The example above shows a request for access to the Employees and PayItems endpoints in the Payroll API.

  • Private applications

    During the beta period you’ll need to follow this link to add a private application which has the necessary permissions to use the Payroll API endpoints

    Pagination

    • 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. In the future the number of pages available for a response will be returned in the header of the response

    Troubleshooting Permissions Errors

    • HTTP 401 error when making API calls

      Possible causes include : trying to access an endpoint that requires permissions and your access token doesn’t have the correct privileges.To resolve this issue you’ll need to get the user to reauthorise your app and make sure you specify the scope parameter with the required endpoints

    • Authorise Screen

      A user will not be able to authorise your application if you require access to payroll endpoints when any of the following criteria are true

      • The user does not have payroll admin permissions for the selected organisation
      • The selected organisation does not have the payroll feature enabled

    API Previewer

    The API Previewer can be used with the Payroll endpoints during the beta release. The payroll endpoints are at the bottom of the endpont dropdown list. Try now