eSignature Embedded Views update

Summary

We’re upgrading the Embedded Sender View, Embedded Edit View, and Embedded Template Edit View API methods in three important ways:

1. Previously, the embedded views could only be used if the application/browser user had the same data and envelope access privileges as the API user. Available now for developer accounts on demo, the two can be different.
2. The new versions will be significantly easier to use in your applications: Today, the Sender View user experience (UX) can be changed programmatically, but it is not simple for the developer to do so. The new API feature enables much easier UX changes.
3. The new Embedded Sender version includes some additional UX controls as well.

Introduction

TL;DR: This update to the embedded view APIs includes full backwards compatibility. Current applications will continue to work. Backwards compatibility mode is used when the viewAccess attribute is not included in the API request. But there are two notes:

1. All applications should be updated due to significant Application Security issues with the current software (more details below).
2. The new version fixes a user experience bug that can be a change for specific situations (see below).

The Docusign eSignature API includes multiple API features that enable developers to directly include parts of the Docusign web application into their own applications.

The Embedded Sender View enables the application user to update and send an envelope. The application user can add or update the envelope recipients, documents, document fields (tags), and envelope metadata. iFrames are supported.

The Embedded Template Edit View is a powerful tool: applications can use it to empower their users to create or edit templates. The templates can include the envelope’s documents, recipients, and authentication settings. Then the application sends the envelopes using the templates. This provides extensive flexibility to the application at a very low cost.

Docusign recommends that all developers consider using templates instead of programmatically creating an EnvelopeDefinition object from scratch. Remember that templates can be combined and updated when the envelope is sent by using the Docusign Composite Templates feature.

The Embedded Edit View API is actually a synonym for the Embedded Sender View. The two have the exact same functionality. So we request all developers currently using the Embedded Edit View to switch over to calling the Embedded Sender View as a part of updating to the new API.

New! Embedded Views Tool

The new Embedded Views Tool enables developers to experiment quickly with the Embedded Sender and Embedded Template Edit views. (Remember, the Embedded Edit View is the exact same as the Embedded Sender View.)

The tool enables you to save a configuration and then reuse it later.

Embedded View application security

Some terminology: the “API User” is the account user who created an access token or, for the JWT Grant OAuth flow, the impersonated account user. The “application user” or “browser user” is the person interacting with Docusign via the browser or the developer’s application. A “service user” is a user account that represents an application, not a person.

Currently, the Embedded Sender, Edit, Correct, and Edit Template views can only be used if the application’s user also has access to the same account(s) and envelopes as the API user.

Example: your application uses the JWT Grant OAuth flow to impersonate a service user. Therefore the service user is the API user. The application uses the Sender View to enable the app’s users to send envelopes created by the application. This is only ok if all of the app’s users should also have read/write/delete access to all of the envelopes and account data of the service user. Otherwise, the app’s users could gain unauthorized access to envelopes and to the account.

New! Security update

To enable more use cases and increase security, we are updating these embedded views to limit their access to only the envelope or template used in the view. With the new security feature, the application user can be anyone; via the Sender View, they will only have access to the one envelope. Via the Template Edit view, they will only have access to the specific template.

Related objects can be accessed through the views. For example, when editing an envelope with the Sender View, the user can add or apply a template accessible to the API user who made the EnvelopeViews API call.

The Embedded Correct View will be updated in a later release.

Another example: Your application uses a service user hr@company.com, as the app’s API User to log in to Docusign and present a Docusign embedded sender window to the company’s managers, enabling them to send envelopes as hr@company.com. With this update, managers using the Embedded Sender View will only have access to the envelope they’re editing. Unlike today, they won’t be able to access other HR envelopes sent via Docusign.

To enable the new API method, including the new security features, include viewAccess: "envelope" in your API request body (see the API section below). For template editing, use viewAccess: "template".

Changing the Embedded View UX

Today, the Embedded View user experience (UX) can be changed programmatically, but it is laborious for the developer to do so. To change the UX, today the developer must modify the response URL from the API call, both adding new query parameters; and searching for and then modifying existing query parameters.

New! Much easier Embedded View UX controls

Instead of manipulating the response URL, the updated Embedded View request object is used to set the UX for the resulting view. This programming style is much easier and more convenient for developers.

New! More Embedded View UX controls

We’ve also added more UX controls to enable developers additional control over the user interface. This release enables the recipient contacts list to be removed. Later releases will enable additional control over the UX.

Bug Fix

Previously, when the eSignature API was used to remove document editing options, the envelope’s documents could still be edited, added, and deleted from the Prepare page. With this release, if the envelope’s documents can’t be changed on the Tagging page, they won’t be changeable from the Prepare page either.

API Updates

To enable the new features, the v2.1 eSignature REST API has been updated.

The API request object was:

{
	"returnUrl": "https://app.example.com" // optional
}

To use the new features (the new version of the API), the minimal request object is:

{
	"returnUrl": "https://app.example.com", // REQUIRED
	"viewAccess": "envelope" // required for envelope views
	// use "template" for embedded template edit view
}

Notes:

• The new API methods provide full backwards compatibility for existing applications: current applications should continue to work without modification. But the backwards compatibility mode has the same security issues as the existing version.
• While backwards compatibility exists, applications should be upgraded as soon as possible to take advantage of the new security features. To use the new security features, specify at least the returnUrl and viewAccess attributes. 
• While the overall definition of the request object is now much larger, all but two of the attributes have a default. The smallest request object is shown above. 
• If your use case requires the application user to see the Docusign web app home page (the “console view”) after they send the envelope, update your application to 1) specify the returnUrl and viewAccess attributes, and 2) use the EnvelopeViews:createConsole API method to redirect the application user after the sender view has completed.
• If your application requires the user to simultaneously use the Docusign web app and one of the embedded views, you must open one or the other in an incognito browser tab. Use the incognito attribute of the windows.create call.
• All applications should be updated to use the new version of the API method. 
• All new ISV applications (ISV-R, ISV-General, ISV-L, and ISV-Embed programs) must use the new version of the API method. Existing ISV applications must plan their updates too.

Here’s the new EmbeddedSenderView request object definition and its defaults:

{
    "returnUrl": , // url required
    "viewAccess": "envelope", // required  
    "settings": {
        "startingScreen":  //"Prepare" or "Tagger"
        "sendButtonAction": // "send", "redirect",
        "showBackButton":  // "true", "false"
        "backButtonAction": // "previousPage", "redirect"
        "showHeaderActions": // "true", "false",
        "showDiscardAction": // "true", "false",
        "lockToken": // token_value,
        "recipientSettings": {
            "showEditRecipients": // "true", "false",
            "showContactsList": // "true", "false"
        },
        "documentSettings": {  
            "showEditDocuments": // "true", "false",
            "showEditDocumentVisibility": // "true", "false",
            "showEditPages": // "true", "false",
        },
        "taggerSettings": {  
            "paletteSections":  // "default", "none", "custom"
            "paletteDefault": // "custom", "merge", "notary", "seals",
            // "smartContracts", "annotations", "smartSections"
        },
        "templateSettings": { 
            "showMatchingTemplatesPrompt": // "true", "false"
        }   
    }
}

And here’s the new EmbeddedTemplateEditView request object definition:

{
    "returnUrl": , // url required
    "viewAccess": "template" // required  
}

Details on the new API method format and its attributes will be published in the Developer Center soon.

New API checks

With the new release, the Embedded View API methods include these updates:

1. The Embedded Sender and Embedded Edit views can only be used with envelopes in the draft (“sent”) state. Otherwise the error Envelope_Invalid_Status will be returned with the error message Sender view cannot be created for an envelope that is not in a draft state.
2. Invalid API requests will be rejected with the error Input_Validation_Error; for example, if an invalid value for the viewAccess attribute was supplied.

Schedule

• The new API method is available now for Developer accounts (the demo platform).
• General Availability (GA): DevCenter documentation and the Production accounts will be updated in June. 

FAQ

1. Why are the Embedded view APIs being updated? The current versions have an application security issue if the API user is not the same as the application user. Because of the security issue, this use case is not supported. The update will enable this use case and eliminate the issue.
2. Will the Embedded Correct View be updated? Yes, we will update it in the future.
3. Does the Embedded Recipient View (the embedded signing ceremony) have the same application security issue? No. It can be used by an application user who is not the API user.
4. I currently use the Embedded Sender View with no returnUrl. (The application user is taken to the Docusign web app home page when they’re done sending the envelope.) Do I need to update my application? Yes, you should update your application to use the new, more secure version of the sender view. You will also need to make a new API call to obtain a console view after the application user sends the envelope.
5. Why can’t the new version of the API continue to support the “no return URL” pattern? There is no practical way to continue the existing pattern and update the security of the API method. It is appropriate to separate the two functions (sender view and console view.)
6. Will the v2 eSignature REST API be updated? No. To use the new features you must upgrade to v2.1. (And you’ve been meaning to do that, right?)
7. Any other benefits to the new embedded view API methods? Yes, we have added more UX controls. The developer can now control availability of the contacts list. And the API update supports additional UX controls for future releases.
8. I’m a customer developer; do I have to make any immediate changes? The new API version provides full backwards compatibility, so you can update on your own schedule. But you’re advised to update as soon as you can. This answer also applies to applications created by SIs and consultants for specific end customers.
9. I’m an ISV; do I have to make any immediate changes? You need to start planning immediately. New applications: starting two months after the GA date, all new applications entering production must use the new API method. Existing applications will also need to be updated. For more information, contact the partner team via the Partner Portal’s Partner Support Form.  
10. How long will it take for a developer to update their application to the new version of the API method? Docusign estimates that it will take a developer less than a day for the update, including testing.
11. Will Docusign turn off the embedded views backwards compatibility mode? At some point, yes. But there will be adequate time to enable applications to be updated. Today, there is no schedule for deprecating the backwards compatibility mode. When there is a deprecation schedule, it will be announced in the release notes.

Upgrading to the new version of the API

In this example, the Embedded Sender View is used. In this use case, the application user should be able to add and update the Docusign fields (tags), but not change the recipients or documents.

To accomplish this, the UX is set to start the Embedded Sender View on the tagger page, and to remove the Back button and document edit options.

// This example uses the older EnvelopeViews.createSender API format

// create the envelope
const envelopeId = createEnvelope();

const qpSender = { // query parameters
      showBackButton: "false"
    , send: "1" // start on the tagger screen
    , showEditDocuments: "false" }
// Make the createSender API call
const senderRequest = { returnUrl: dsReturnUrl };
const apiMethod= `/accounts/${accountId}/envelopes/${envelopeId}/views/sender`;
// callApiJson makes the API call and returns the decoded JSON result
const results = await callApiJson({
    apiMethod: apiMethod,
    httpMethod: "POST",
    req: senderRequest
});
const qp = new URLSearchParams(qpSender); // create the query parameter string
// munge the results URL...
const resultsUrl = results.url.replace(/&send=[01]/,''); // remove "&send=x"
const senderUrl = `${resultsUrl}&${qp.toString()}`; // add the new query params
window.open(senderUrl, "_blank");

With the old API format, the developer must change the response URL received from the EnvelopeViews:createSender API call.

With the new API format, the developer uses the response URL directly, as would be expected. The UX controls are added to the API request. Result: the application is shorter and simpler:

// This example uses the new EnvelopeViews.createSender API format

// create the envelope
const envelopeId = createEnvelope();

// Make the createSender API call
const senderRequest = {
      returnUrl: dsReturnUrl
    , viewAccess: "envelope"
    , settings: {
          startingScreen: "Tagger"
        , showBackButton:  "false"
        , documentSettings: {  
             showEditDocuments: "false",
        }
    }
}
const apiMethod= `/accounts/${accountId}/envelopes/${envelopeId}/views/sender`;
// callApiJson makes the API call and returns the decoded JSON result
const results = await callApiJson({
    apiMethod: apiMethod,
    httpMethod: "POST",
    req: senderRequest
});
window.open(results.url, "_blank"); // no changes to the returned URL

Additional resources

• Docusign Developer Center
• Docusign Developers Community
• @DocuSignAPI on X
• Docusign for Developers on LinkedIn
• Docusign for Developers on YouTube
• Docusign Developer Newsletter