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.
This document will be covering the necessary integer ID to unique identifier migration.
The purpose of API changes is to remove numeric system IDs and replace them with unique UUIDs.
Note: To aid with the upgrade to V3 we will introduce a Transition Mode to the current API (v1). 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. More on this process later.
The changes affect three areas:
Subsections below give a high-level overview of these changes, while Detailed Changes section lists specific changes in each method.
In some areas of the API, IDs have a special meaning (e.g. Job Numbers). In those areas, the <ID> field remains unchanged. This applies to the following elements:
See Detailed Changes section for information on each individual method.
For URLs, [id] in URL is replaced with [uuid].
For example:
Before (API v1) |
Now (API v3) |
GET client.api/get/123 |
GET client.api/get/99a47d7c-2f3a-47ae-b57e-44c98df21094 |
Specific list of affected URLs can be found in the Detailed Changes section.
URLs that use a non-[id] identifier are not changed.
For example, job.api/get/[job number] is not changed.
For responses, <UUID> is returned instead of <ID> or <InternalID>.For example:
Before (API v1) |
Now (API v3) |
<Response> <Name>Client 1</Name> |
<Response> <Name>Client 1</Name> |
As mentioned before, in some cases <ID> has a special meaning (e.g. in <Job>).
In those cases, <ID> is preserved and <UUID> replaces <InternalID> instead.
For example:
Before (API v1) |
Now (API v3) |
<Response> <InternalID>123</InternalID> <Name>Job 1</Name> |
<Response> <ID>J1</ID> <Name>Job 1</Name> |
For requests, <UUID> should be sent instead of <ID>.
Same applies to similar elements, e.g. <BillingClientID> becomes <BillingClientUUID> and <add task="…"> becomes <add task-uuid="…">.
In some cases (e.g. <Job>) where <ID> has a special meaning, <ID> is preserved and <UUID> is not used.
For example:
Before (API v1) |
Now (API v3) |
<Client> <Name>Client 1</Name> <BillingClientID> |
<Client> <BillingClientUUID> </BillingClientUUID> |
<Contact> <Name>New</Name> |
<Contact> |
<!-- job.api/assign --> <ID>J1</ID> <add id="123" |
<!-- job.api/assign --> <Job> <ID>J1</ID> <add uuid="3dfce393-5c9a-4be7-9d63-6b85e048accb" </Job> |
See "API v3 Breaking Changes" specification for full details on API changes.