eSignature REST API Embedded Correct View now updated

In June, we updated the Embedded Sender View, Embedded Edit View, and Embedded Template Edit View API methods. Now we’ve updated the EnvelopeViews:createCorrect API method, too. It’s on demo now; the production environments will be updated by mid-July.

For general information on the API updates, see the blog post eSignature Embedded Views update.

Introduction

The Embedded Correct View enables the application user to modify an envelope after it’s been sent and before it is complete. Completed envelopes can’t be modified.

This update to the Embedded Correct View API method 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 note: All applications should be updated due to significant application security issues with the current software.

Embedded Views Tool updated

The new Embedded Views Tool has been updated to support the new EnvelopeViews:createCorrect API method. The tool enables you to save a configuration and then reuse it later.

Embedded View application security

As discussed in the prior blog post, the new versions of the API methods use an access token that is restricted to making changes in the specific envelope of the correct view. This is much safer than the older form of the API methods, which potentially granted too much access.

All applications should be updated to use the new versions of the API methods. A deprecation schedule will be announced in August.

To enable the new API functionality, 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, 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.

API updates

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

The active attributes for the API request object were:

{
	"returnUrl": "https://app.example.com", // optional
	"beginOnTagger": "true" // or "false"
}

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 method provides 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. 

• All new ISV applications (ISV-R, ISV-General, ISV-L, and ISV-Embed programs) must use the new version of the API. Existing ISV applications must plan their updates too.

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

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

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

New API checks

With the new release, the Embedded View APIs include these updates:

1. The Embedded Correct view can only be used with envelopes in the sent state; otherwise, the error Envelope_Invalid_Status will be returned.

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 is available now for developer accounts (the demo platform).

• General Availability (GA): Production accounts and DevCenter documentation will be updated in July. 

FAQ

1. Why are the Embedded View APIs being updated?The current versions have an application security issue that arises when 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. Does the Embedded Recipient View (the embedded signing session) have the same application security issue?No. It can be used by an application user who is not the API user.

3. 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.

4. 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).

5. 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?)

6. Any other benefits to the new Embedded View APIs?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.

7. 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.

8. 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. Existing applications will also need to be updated. For more information, contact the partner team via the Partner Portal’s Partner Support Form.  

9. How long will it take for a developer to update their application to the new version of the API?Docusign estimates that it will take a developer less than a day for the update, including testing.

10. Will Docusign turn off the Embedded Views backwards compatibility mode?

Additional resources

• Docusign Developer Center

• Docusign Developers Community

• @DocusignAPI on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter