What's New in eSignature API v2.1

Version 2.1 of the Docusign eSignature API includes usability updates, new features, and better tools for handling large workloads and bulk operations. It is an incremental but substantial update to the existing v2.0 eSignature API.

Improved usability

Improving usability is a major goal of the v2.1 API. Many API responses now return more useful and standardized sets of data, and you are now able to customize what data is returned by many requests, based on your needs. New URL parameters such as include={data}, exclude={data}, and include_metadata help you minimize the number of API calls that you need to make to get all the information you need (and less information that you don’t).

Many properties throughout the API now have a corresponding Metadata properties that indicate whether the property has additional options, or if it is editable. Where possible, parameters have been standardized to string format, and objects that used comma-separated string formats (such as some properties within Tab, Envelope, and Template objects) have been converted to string array format to make development smoother and easier.

Envelope search

Version 2.1 of the Docusign eSignature API introduces new filters and capabilities for envelope search that enable you to search precisely and flexibly for specific sets of envelopes and tailor search functionality to use our API to build UI functionality for your applications. You can now filter your search results by providing parameters that specify attributes (such as text, a common folder, or a common user involved in the signing process) that all returned envelopes must have.

You can also include or exclude additional metadata from the returned envelope data, including:

The recipients, PowerForms and/or folders associated with the returned envelopes.
Data on purged or deleted information associated with the returned envelopes.

Search results may also be ordered in ascending or descending order by any envelope property.

See Searching for Envelopes for details.

Bulk sending envelopes

The ability to bulk send envelopes (or to send copies of an envelope to a list of recipients) has been extensively updated in version 2.1 of the API. You can now customize the envelope to be sent to multiple recipients (per copy), use custom fields (tabs), perform validation checks to ensure that your list of recipients is valid, and use the full range of Docusign capabilities that apply to non-bulk sending such as authentication, embedded signing, and customized messages.

These updates are summarized in the following table:

Bulk Send in the v2.0 API	Bulk Send in the v2.1 API
Can use envelopes	Can use envelopes and templates
Single recipient per envelope	Multiple recipients per envelope
Only recipient name and email can be customized	Each recipient in each envelope can be individually customized just as you would in a normal envelope send operation, including capabilities such as: Identity Authentication Methods such as access code, SMS authentication, and IDV Embedded signing Customized tab values Customized email messages
No validation	Optional pre-send validation check
Custom fields are not supported	Custom fields are supported

See Bulk Sending Envelopes for details.

Templates are now organized within folders, which group similar templates together and allow you to share groups of templates with other users, rather than sharing them one-at-a-time.

You can share your templates (either a single template or a folder containing one or more templates) with:

An account, specified by accountId
A user, specified by userId
A group, specified by groupName

Note: If you choose to share a template folder with one or more users, accounts, or groups, any new templates you later add to that folder will also be automatically shared.

See Sharing templates for details.

CC recipient commenting

Carbon Copy (CC) Recipients may now make and respond to comments in the documents belonging to the envelopes that they are sent. A new object, Comment, has been added to contain their comment data.

Each comment may be up to 500 characters. See Comment for details.

Witness recipient identity authentication

A new type of recipient Identity Authentication, witness authentication, has been added. This method of authentication requires that you create a recipient with the new witness type, who must be viewing each document as it is signed.

To use witness authentication:

Create at least one recipient in your envelope and assign the new witness type to it.
Set the envelope to use the witness type of recipient authentication.
During the signing workflow, each recipient that is assigned the witness type must view the documents in the envelope after they are signed.

Typically, a witness will be in the same room as the signer but this guidance is not enforced by Docusign.

API object model updates

Many properties throughout the API now have a corresponding Metadata properties that indicate whether the property has additional options, or if it is editable. For example, the name property may have a nameMetadata property that indicates whether the name is editable.

The Document, Envelope, Tab, Recipient, User, and Template API endpoints have been updated to improve usability and support new capabilities, as outlined by the following table:

Object	Updates in API v2.1
Documents, Templates, and Envelopes	New endpoint query parameters: `include_metadata`: Enables you to include sets of metadata in the response when getting documents. When this parameter is true, responses will include metadata fields. Note that you cannot include metadata for template responses. `shared_user_id`: Enables you to impersonate a shared inbox user to retrieve their view of a list of documents. `documents_by_userid`: Enables you to order documents by their user IDs when getting a list of documents. For example, if a user is included in two different routing orders with different visibilities, using this parameter returns all of the documents from both routing orders. `recipient_id`: Enables an envelope sender to retrieve documents as though they were one of the recipients. The `documents_by_userid` parameter must be false to retrieve documents in this way. New capabilities: Document endpoints that add documents to get documents from an envelope may now be passed an Envelope object, rather than just an ID. Encoded unicode characters in document file names are now supported when adding or updating a document, if a Content-Disposition header is included. Calls that retrieve document data now return a new Pages object (which contain Ids, sequence numbers, height, width, and DPI information for each page in the document) rather than a count of the total number of pages. All comma-separated value properties have been changed to string arrays.
Recipients	New endpoint query parameters: `include_metadata`: Enables you to include sets of metadata in the response when getting documents. When this parameter is true, responses will include object metadata fields. Note that you cannot include metadata for template responses. `Include_tab_count`: For operations to get recipient data, enables you to specify that the response will also include data on the total number of tabs assigned to the recipient. New capabilities: CC recipient types have a new tabs property that holds their Comments. These objects contain the data for each comment left by the CC recipient. In-person (embedded) signers may now have their name set in two properties, `signerFirstName` and `signerLastName`. Notary hosts may now be set as a signing group. Operations to get recipient data now also return a `RecipientType` property denoting the types of each recipient. Docusign now tracks how many times each recipient has been through a signing completion for that envelope with a new property, `completedCount`. If the value of this property is more than 0 for a signing group, only the user who previously completed signing may sign again. A new type of recipient authentication, `witness`, has been added. This type of recipient authentication requires that a specified recipient (who must have the `witness` type) must be view the signed documents before it can be completed.
Tabs	New endpoint query parameters: `include_metadata`: Enables you to include sets of metadata in the response when getting tabs. When this parameter is true, responses will include object metadata fields. New capabilities: New metadata properties have been created to contain metadata for many existing tab properties that indicate whether the sender can edit that property. A new tab type, PolyLineOverlay, is now available. This tab type enables users to strike out text on a document.
User	New capabilities: The `userSettingsInformation` object has been expanded to contain additional user setting information related to PowerForm access, permissions, time zone/locale, commenting, and metadata.