DocuSign eSignature API v2.1 Unveiled
The DocuSign eSignature REST API v2.0 has been around for several years. While we've made continuous improvements to the existing API, there are limits to what can be done to maintain compatibility with existing integrations. DocuSign has been working on an iteration of our API that our first party apps including our web app uses. This iteration is the new eSignature API v2.1. It is an incremental improvement on its predecessor, so you will find much familiarity. There are three main areas of improvement:
- Improved usability
- New features
- Handling large workloads
Improved usability
Usability is at the forefront of many improvements in the eSignature API v2.1. You will start noticing API responses returning more useful and predictable data. You will also have the ability to customize what is returned, based on your needs.
As an example, fetching envelope data in the past didn't return who the sender was, and there wasn't an easy way to determine this information. We have streamlined the developer experience by eliminating comma-separated strings and moving to arrays, standardizing all parameters as strings to take the guesswork out of data types. We also standardized entity models, like Envelopes and Templates. All of these small, incremental improvements will help make development smoother and easier.
Developers have also long asked for the ability to customize responses. While we are not pursuing the likes of graphQL in a minor version update, we have borrowed the spirit of the goal by allowing developers to customize what is returned using the URL parameters with include={data} or include_metadata=true. This enables you to minimize the number of API calls and get back what you need in the same call.
Here’s an example response for the GET https://{{hostenv}}/restapi/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/recipients?include_metadata=true call:
{
"signers":[
{
"signInEachLocationMetadata":{
"rights":"editable"
},
"creationReason":"sender",
"isBulkRecipient":"false",
"recipientSignatureProviders":[
{
"sealDocumentsWithTabsOnly":"false",
"signatureProviderNameMetadata":{
"rights":"editable"
},
"signatureProviderOptions":{
}
}
],
"identityVerification":{
"workflowId":null
},
"name":"Signer Num1",
"nameMetadata":{
"rights":"editable"
},
"email":"fname.lname@docusign.com",
"emailMetadata":{
"rights":"editable"
},
"signingGroupIdMetadata":{
"rights":"editable"
},
"recipientId":"1",
"recipientIdGuid":"961cf6e9-xxxx-xxxx-xxxx-354361cae33b",
"accessCodeMetadata":{
"rights":"editable"
},
"requireIdLookup":"false",
"requireIdLookupMetadata":{
"rights":"editable"
},
"idCheckConfigurationNameMetadata":{
"rights":"editable"
},
"smsAuthentication":{
"senderProvidedNumbersMetadata":{
"rights":"editable"
}
},
"userId":"5e0d6fd5-xxxx-xxxx-xxxx-c412f7e33596",
"routingOrder":"1",
"routingOrderMetadata":{
"rights":"editable"
},
"noteMetadata":{
"rights":"editable"
},
"status":"delivered",
"completedCount":"0",
"deliveredDateTime":"2019-05-16T20:52:31.2800000Z",
"deliveryMethod":"email",
"deliveryMethodMetadata":{
"rights":"editable"
},
"faxNumberMetadata":{
"rights":"editable"
},
"recipientType":"signer",
"recipientTypeMetadata":{
"rights":"editable"
}
}
],
"agents":[
],
"editors":[
],
"intermediaries":[
],
"carbonCopies":[
],
"certifiedDeliveries":[
],
"inPersonSigners":[
],
"seals":[
],
"witnesses":[
],
"recipientCount":"1",
"currentRoutingOrder":"1"
}
|
New features
DocuSign eSignature v2.1 offers many new features that weren't available in the previous API. While you may be familiar with many of these features through our web application, this will be the first time many of these will be made available to developers. Below is a flavor of new capabilities, the full set will be released along with the official Documentation in June.
- Template access management: ability to manage templates by folders
- New Bulk Send
- Envelopes: Revamped envelope search that lets applications search across folders, PowerForms, users, include/exclude a variety of metadata, and most importantly, text search, allowing developers to use an API to build a UI for their own applications.
- Comments
Bulk Send is very popular for mass distribution scenarios. Below is an example of the type of enhancement we've made. Bulk Send capabilities existed in the eSignature API v2.0, now has additional capabilities in v2.1, as shown in this table:
| Bulk Send in v2.0 API | Bulk Send in v2.1 API |
| Can use envelopes | Can use envelopes or templates |
| Single recipient per envelope | Multiple recipients per envelope |
Single recipient in each envelope can customize:
|
Each recipient in each envelope can be individually tailored, supporting the whole suite of DocuSign capabilities, similar to regular sending flows:
|
| No validation | Pre-send validation check |
| No custom fields | Supports custom fields |
Handling large workloads
For our enterprise customers, managing hundreds of thousands of envelopes can be a tedious affair. Queries can time-out, and querying across historical data can take a long time. The eSignature API v2.1 will allow customers a way to retrieve and search envelopes through a chunking process to handle large data volumes. For mass retrieval, we will soon release a Data Feed API, which will enable you to retrieve data into your own data warehouse.
What's next and how to get started with the v2.1 eSignature API?
The eSignature API v2.1 will be publicly released and made available at our upcoming Momentum 2019 Conference. This is a great opportunity for you to join us and learn about our new products, capabilities, and new developer capabilities. Developers can register and attend for free!
The public content, including an updated API reference, guides, and code examples, will be made available June 11th. At that time you can simply switch your API calls from {host]/restapi/v2/accounts/{accountId}/ to {host}/restapi/v2.1/accounts/{accountId}/. For those using our SDKs, a new versions will also be released. All eSignature v2.1 information will be available in our DeveloperCenter.
