Upgrading from API v2.0 to v2.1
The release of version 2.1 of the Docusign eSignature REST API brings a host of new features and usability improvements. For an overview, see What’s new in eSignature API v2.1. Check the API reference for details. Upgrading your existing integrations from v2.0 to v2.1 of the eSignature REST API gives you the opportunity to take advantage of these new capabilities, but changes in v2.1 may require you to update your code.
Changes appear in the following areas:
- The syntax of API calls and SDK methods
- The available parameters and their associated data types
- The structure or data types of the request or response objects
One example of a change that may require code updates is the improved standardization of return parameters. For example, v2.0 of the API returns some parameters as comma-separated strings, as shown in the following examples:
In v2.1, these parameters are separated into arrays of strings:
This change improves usability because you no longer have to parse a long string to extract a single value, but it will break integrations that expect to parse such a string.
Tab alignment
The placement of the signHere and initialHere tabs have changed for v2.1.
In v2 of the eSignature API, when you used fixed positioning for the signHere tab, the tab appeared 21 pixels lower on the final PDF document than the value you provided for the y-coordinate. To align the tab as expected, you had to subtract 21 pixels from the expected y-value (+0, -21) to make it appear where you expected during the signing view.
For the initialHere tab, you had to subtract 16 pixels from the expected y-value (+0, -16) to make it appear where you expected.
We have corrected these tab placement issues in v2.1 so that placement is much more accurate. However, as a result, when you migrate from v2 to v2.1 of the eSignature API, you will need to update your fixed tab coordinates by adding +21 back to the y-coordinate for the signHere tab and +16 back to the initialHere tab, since you will no longer need to account for the erroneous v2 downshifts for these tab types.
This image demonstrates the v2.0 (+0, -21) shift for signHere tab positioning in the signing view:
This image demonstrates the v2.0 (+0, -16) shift for initialHere tab positioning in the signing view:
Updating your code: Direct API calls vs. using an SDK
The changes to the eSignature REST API for version 2.1 will impact your integration differently depending on whether you called REST API endpoints directly or used one of the Docusign eSignature SDKs.
Direct API calls
Integrations built by using direct calls to the REST API may break on endpoints that are affected by changes in v2.1. See the list of changes that may cause breaks below.
Use the following steps to upgrade your integration to v2.1:
- Test your integration to determine whether it is failing, and if so, on which API calls.
- Check the API reference to find out how to make the calls you need to the API v2.1 endpoints.
- Update your code to account for the API changes, recompile the code, and retest.> Note: With direct API integrations, calls to endpoints not affected by the v2.1 changes do not need to be updated. You can make calls to both API v2.0 and API v2.1 endpoints in the same integration.
Endpoints that contain changes in Docusign eSignature REST API 2.1:
Using an SDK
We have also released new versions of our SDKs for the eSignature REST API v2.1. To upgrade your integration to API v2.1, you will need to adopt the latest version of your SDK.
Use the following steps to upgrade your integration to v2.1:
- Upgrade to the latest version of the SDK using the package manager for your programming environment.
- Recompile your integration using the new SDK version to see if any errors are generated.
- Update your code to account for the changes, recompile the code, and retest.
SDK version numbers: