API Documentation

You’ll need to upgrade to API v3 to keep your connection live

What’s happening

As a 3rd party developer, you need to know about planned changes to the WorkflowMax API which will affect you and your customers.

Splitting the current version of the API

We are splitting the current version of the API so there will now be a WorkflowMax API (WFM API) and a Xero Practice Manager API (XPM API). 

If the application you have developed has customers using both WorkflowMax and Xero Practice Manager accounts, your app will need to be aware of the difference and call the relevant URLs. It will not be possible for your WorkflowMax customers to use the Xero Practice Manager API and vice versa.

Moving behind Xero’s API gateway for greater security

Both the new WFM and XPM APIs will move behind Xero’s api.xero.com gateway, so you’ll have to call a new URL and register your app.

Migrating to OAuth 2.0 for more secure and automated customer connections

Xero's API gateway uses the OAuth2.0 standard which will provide secure delegated access to users' information. App users will no longer have to request and manually manage access keys – they will grant access to their account via a familiar consent flow. App developers will need to implement the OAuth2.0 flow in their apps in order to continue accessing users' WFM information. 

Changing from ID to GUID identifiersIn order to enable future growth for WorkflowMax, we are switching from using integer identifiers to using unique GUID identifiers. This is recommended as industry best practice and provides an extra layer of security against direct object reference attacks.

Some app partners will need to complete a security self-assessment

App partners using the new WFM API (Business API) will now be required to complete a security self-assessment questionnaire once they reach 1000 connections. There's more detail about the assessment and when it needs to be completed below.

Key dates

• - 6 April 2020: The v3 API will be available for migration.

• - 30 Nov 2020: All WFM app partners are migrated. 

What you need to do between 6 April and 30 November 2020

1/ Migrate your integer identifiers (ID) to GUID identifiers (UUID) for all references that you store on your local database. This is already available on the current WorkflowMax API and needs to be updated prior to using the new WorkflowMax API in Xero. The instructions and migration guide for this will be available on 6 April 2020 here.

2/ Navigate to the Xero Developer Portal, click the ‘New app’ button, fill in all required details, and click ‘Create app’.

3/ Note that you (or another administrator on the Account) will need to enable the “Allow 3rd Party Access” privilege for your User on the account (Business -> Settings -> Staff) to allow you to authorise the connection with your Application.

4/ Implement auth Xero Gateway (OAuth 2.0) as per the Xero API Documentation.

5/ Change your integration to call the new Xero API URLs (eg https://api.xero.com/workflowmax/3.0/client.api/list) using the access tokens retrieved via your OAuth2.0 implementation.

6/ If you have more than 1000 connections to this API, fill in the security self-assessment questionnaire when requested.

7/ After you’ve made the changes above, communicate with your customers who are using the WorkflowMax integration.

More about the security self-assessment requirement for app partners

If you have more than 1000 connections then you need to complete the security self-assessment by 30 June 2020. 

If you do not have 1000 connections yet, we’ll contact you when you have 800 connections to give you time to complete the self-assessment. Your connection limit will be restricted to 999 connections until you have completed and passed the self-assessment. 

Full details of the requirements can be found here.

API access will be restricted if the self-assessment isn’t successfully completed, and any issues remediated, within an agreed timeframe.

The security self-assessment will need to be completed on an annual basis.

Full documentation of all the API and security changes will be available here on the Xero developer website from 6 April 2020. Contact us if you have any questions.