With our community of partners, you can get expert advice and training so you can be up and running in no time!
View setup partnersWith our community of partners, you can get expert advice and training so you can be up and running in no time!
View setup partnersGet the Guide on Moving from spreadsheets to software.
Want to join us? Become a partner.
No credit card required. No contracts to cancel. No setup fees. No hidden costs. No downloads.
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 :
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:
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.
If the url you are using have no version number, and is still using https://api.workflowmax.com, then you will need to upgrade.
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.
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.
Adjust your implementation of the WorkflowMax API so that it can accept the new UUID fields.
For each WorkflowMax entity that you store an ID, adjust your storage solution so that you can also store a UUID against that entity.
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.
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.
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
The v3 API is now only available from the Xero Gateway, and is accessible from https://api.xero.com/workflowmax/3.0/
Remove uuidMode=transition from your query string.
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.
Stop storing any numeric IDs
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.
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.
For requests that contain an ID in the URL
For requests that contain an ID in the Body
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.