API Documentation

Important changes to the API coming soon

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

What’s happening and what you need to do

Because you have an API connection enabled on your WorkflowMax account to access the WorkflowMax API, you need to know about planned changes to the WorkflowMax API which will affect you.

If you’ve paid for a bespoke integration between a system or website which you own (or subscribe to), and your WorkflowMax account, then you’ll need to engage a developer to make the changes for you. If you need a developer, you’ll find a listing of custom integrators on the Xero App Marketplace.

Please share the information and instructions below so they can upgrade your connection by 30 November 2020. 

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 users from both 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 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/XPM information. 

Changing from ID to GUID identifiers
In 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.

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

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 on the Xero developer website from 6 April 2020. Contact us here if you have any questions.