With our community of partners, you can get expert advice and training so you can be up and running in no time!

View setup partners

With our community of partners, you can get expert advice and training so you can be up and running in no time!

View setup partners

Get the Guide on Moving from spreadsheets to software.


Get the guide

Want to join us? Become a partner. 



Become a partner

WorkflowMax API Upgrade Guide: Version 1 to Version 3

Important Notice:

A previous version of this guide referred to using the API URL https://api.workflowmax.com/v3/
While this URL will appear to work, it is not behind the Xero Gateway, and so will be deprecated by the end of the year.  We apologise for any inconvenience caused by this incorrect URL.

You will need to still do the following if you have already switched to the above URL : 

  1. Move to using the new URL https://api.xero.com/workflowmax/3.0/
  2. Update your authentication to use OAuth 2.0
  3. No other Request/Response changes have been introduced with this new URL.

The new v3 API will introduce some breaking changes to the requests and responses. We will be changing all entities that use a numeric ID, to use a new unique UUID. 

Version 3 is going to introduce breaking changes to the current API in the following ways:

  1. New URL - change to use V3 in the url
  2. New Authentication Method - removing the api/account keys from the query string and switching to OAuth 2.0
  3. New data structures - change from <ID> to <UUID> 

To aid with the upgrade to V3 we will introduce a Transition Mode to the current API. This new mode will simply add the new UUID fields to the existing V1 responses where applicable - making it easier to start using the new UUID field. Transition Mode will also allow the use of UUIDs in your requests, making it possible to start using these fields before switching to V3.

What Version Am I on?

If the url you are using have no version number, and is still using https://api.workflowmax.com, then you will need to upgrade.

 

How to deal with each breaking change:

  • New Url requirements - Base URL changes
    • Full details in the Upgrade Guide
  • New Authentication method
    • Full details in the v1 to OAuth migration guide
  • New Data Structures - ID to GUID change

Transition Guide - Only for API consumers that store numeric ID Fields:

If you do not store any numeric ID fields from the WorkflowMax API, you can skip straight to the Upgrade to V3 Guide. See the Exceptions section for more information about the distinction between numeric and non-numeric IDs.

Transition mode allows you to start storing the new UUID alongside any ID

If you do store numeric IDs you can begin the process of transitioning to (only) using UUIDs by simply enabling Transition Mode in your current implementation. This will add the UUID field to all responses that currently use numeric IDs, without changing anything else in the response. You can then begin storing the new UUID values alongside any ID values, to enable you to eventually transition to only using UUIDs.

Step 1.

Add uuidMode=transition to the query string of your current requests.

E.g. https://api.workflowmax.com/job.api/list?uuidMode=transition

The WorkflowMax API will now start including UUID fields alongside any ID fields in the response. This may break your consumption of the WorkflowMax API, depending on your implementation.

Step 2.

Adjust your implementation of the WorkflowMax API so that it can accept the new UUID fields.

Step 3.

For each WorkflowMax entity that you store an ID, adjust your storage solution so that you can also store a UUID against that entity.

Step 4.

Start saving the UUID values from all responses alongside any ID values you are already storing. Upon completing this step you should now have a solution where any time you use the WorkflowMax Api, and save data, you are saving both the ID and UUID.

Over time as your customers use your add-on, the UUID values will be slowly backfilled.

Step 5.

This optional step can be used to download all IDs to UUID mappings at once, instead of filling it in slowly in Step 4.

For each account key linked to an app key, call our ID-to-UUID Endpoint, and download the files generated. For each WorkflowMax entity type (ie Job, Client, Staff, etc) there will be a file listing all your account’s IDs and UUIDs for that entity type. For each ID in each file, find the related entity in your chosen storage solution, and import the UUID value for that entity.

If you are an API Add-on Partner, you will need to repeat this step for each account using your API key and each.

Upon completing this step you should now have a solution where all of your current (and future) data that uses the WorkflowMax ID field has a value for UUID as well. Please ensure this is the case before moving on to the Upgrade to V3 Guide.


Upgrade to V3 Guide - For All API Consumers

If you do not store any numeric ID fields from the WorkflowMax API, or you have completed all steps in the Transition Guide, you are ready to upgrade to V3.

Note: You will need to create a new application under the Xero Developer Portal. Signup for a free Xero account, and then create your application under the portal using this link : https://api.xero.com/Application

Step 1. Change your URL:

The v3 API is now only available from the Xero Gateway, and is accessible from https://api.xero.com/workflowmax/3.0/

Step 1-A. (Transition Users only):

Remove uuidMode=transition from your query string.

Step 2.

Ensure your implementation of the WorkflowMax API can handle the new UUID field(s) and the removal of the ID field(s) as outlined in the V3 schema documentation.

Step 3-A (Transition Users only):

Stop storing any numeric IDs

Step 3.

Implement OAuth 2.0 authentication.  

Web Applications
For a web application, the standard authorization flow is recommended.  The standard flow is the most well known OAuth 2.0 flow and typically used by web server applications. It requires your app to securely use and store a client secret.

Native (desktop and Mobile) Applications
A Proof Key for Code Exchange is supported as well for these apps.  The PKCE flow requires your app to create a secret (called a code verifier) for each authorization request. It’s slightly more complicated to implement but offers a secure way to connect to the API if your app can’t be trusted to store a client secret, for example with Desktop and Mobile apps.

Backend services and Scripts
Where you have no user interface or web server, a slightly more complicated implementation is required.  See our guide for building integrations with no UI using OAuth 2.0.

SDKs

We have a range of new SDKs that integrate with OAuth 2.0. 
There is a Postman collection for WorkflowMax API to experiment with and understand the API and the new OAuth authentication process.
Finally, a sample .Net Core application is available to view and download to jump start your authentication changes.


Quick Tips

For requests that contain an ID in the URL

  • Swap out the ID with the entity’s UUID.
    • GET task.api/get/1232 becomes GET task.api/get/ffa44485-...

For requests that contain an ID in the Body

  • If the XML Node is <ID> and only ever contains numbers
    • Change the Node to <UUID> and swap out the ID value with the entity’s UUID.
    • <ID>456</ID> becomes <UUID>ad759d98-...</UUID>
  • If the XML Node has a descriptor before ‘ID’, eg <StaffID>
    • Keep the Node descriptor the same, but change ID to UUID.
    • <StaffID>123</StaffID> becomes <StaffUUID>daad601a-...</StaffUUID>
    • Note: This also applies to the <InternalID> fields exposed by the Job api and the Invoice api

 

Exceptions

The following <ID> nodes are not numeric and therefore do not require changing: 

Controller

Field Name

Example

 

Job

 

Job Number

<Job>

<ID>J000123</ID>

</Job>

 

Quote

 

Quote Number

<Quote>

<ID>Q000456</ID>

</Quote>

 

Purchase Order

 

Purchase Order Number

<PurchaseOrder>

<ID>PO000789</ID>

</PurchaseOrder>

Invoice

Invoice Number

<Invoice>

<ID>INV0234</ID>

</Invoice>

 

These fields are labeled as <ID> but are referred to as Job Number, Quote Number, Purchase Order Number and Invoice Number respectively in the documentation (ie get/[job number]). V3 will continue to include this <ID> field in the response, and will continue to accept it in any route that documents so. Please be aware that these four <ID> nodes (Job Number, Quote Number, Purchase Order Number and Invoice Number) are the only <ID> nodes that are not numeric and therefore not changing to a UUID.

 

Example Request Using Entity Number

V1

V3

GET get/[job number]

GET get/[job number]

https://api.workflowmax.com/job.api/J00309

https://api.xero.com/workflowmax/3.0/job.api/get/J00309

 

Example Response With Entity Number And Regular Numeric ID

V1

V3

<Job>

<ID>J000309</ID>

<Client>

<ID>678</ID>

</Client>

</Job>

<Job>

<ID>J000309</ID>

<Client>

<UUID>caa9f7a7-...</UUID>

</Client>

</Job>

 

More examples are available on our official V3 documentation page.