Blog
Home/

Introducing new Web Forms API and embedded forms functionality

Gustavo Bitdinger
Gustavo BitdingerPrincipal Product Manager
Summary4 min read

The Web Forms API and the Docusign JS client SDK enable you to seamlessly and securely embed Web Forms in your authenticated web application.

      • Using the Web Forms API to create web form instances
        • Rendering web form instances
            • Additional resources

            Table of contents

            Docusign Web Forms streamline data collection by providing an interactive and seamless form-filling experience for your signers.  With Web Forms, you can speed up form completion and more easily unlock the data within your agreements. 

            Today, we are introducing a new Web Forms API for developers, enabling you to manage web form configurations and instances in your Docusign account.  In addition, we are introducing enhancements to Docusign JS, a JavaScript client library that you can use to seamlessly embed a web form instance in your website.

            With the Web Forms API and Docusign JS library, you can:

            • Ensure that web form instances are secure and unique to an individual user

            • Embed web form instances in an authenticated web application

            • Prefill form fields with customer information from a system of record

            • Monitor the status of web form instances and corresponding envelopes generated after form submission

            • Retrieve user-submitted form data for export to external systems

            Sample web form instance

            A typical implementation will look something like this:

            Web form instance processing

            Using the Web Forms API to create web form instances

            To get started, make sure that you have created and activated a web form configuration in your account.  When a user triggers a process to start filling out a web form on your website, your application should make a POST request to Instances:createInstance, using your account_id and form_id as path parameters and passing additional values in the request body. 

            Below is a sample Instances:createInstance request body that includes a formValues object for prefilling form data:

            {
              "clientUserId": "1234-xxxx-xxxx-efda",
              "formValues": {
                  "name": "Sally Signer",
                  "email": "sally.signer@email.com",
                  "salary": 121800.55,
                  "birth_date": "1980-12-18",
                  "marital_status": "single",
                  "education": "advanced",
                  "alerts": ["Funds_withdrawn","Account_info_changed"]
                },
              "expirationOffset": 720, 
              "returnUrl": "https://developers.docusign.com"
            }

            Notes:

            • clientUserId is the only required property and can be set to any string (up to 100 characters) to identify the user filling out the web form.

            • Fields specified in formValues are referenced by their API reference name (also called componentNames in the API).

            • Date values must always be provided in YYYY-MM-DD format.

            • Number values must be provided with no quotes and no thousand separators and must use a period for a decimal point, if needed.

            • Dropdowns, radio groups, and checkbox groups must reference valid API values; for checkbox groups, you can provide an array of multiple values.

            • expirationOffset is provided in hours; the web form instance can no longer be submitted after it expires.

            • If you plan to redirect to a web form instance URL (rather than use the Docusign JS library), returnUrl enables you to specify a confirmation page for the user after they finish signing.

            Instances:createInstance returns a formUrl and instanceToken that can be used to construct a web form instance URL in the following format:

            https://[formUrl]#instanceToken=[instanceToken]

            For example:

            https://demo.services.docusign.net/webforms-ux/v1.0/forms/333fdc52xxxxxxxxxxxx24c6cc03#instanceToken=U2FsdGVkxxxxxxxxxxxxqgmZHxw=

            Note that the instanceToken expires within 5 minutes.  An error is displayed if your application tries to load a web form instance URL that includes an expired instance token.  However, your application can obtain a new instanceToken by calling Instances:refreshToken, allowing your users to return to the same instance across multiple sessions.

            Rendering web form instances

            Your application can redirect to the web form instance URL, as constructed above, or use Docusign JS to embed the instance in your website.  Docusign JS libraries are available here:

            Some of the benefits of Docusign JS include:

            • A unified experience for users that makes the web form instance appear as if it's hosted on your website

            • A focused view display of the envelope that Docusign generates after a user submits a web form instance. Focused view eliminates some of the Docusign signing UI components, further contributing to a seamless user experience.

            • Display customization options

            • Form and envelope events that your application can use to trigger actions

            You’ll find a sample implementation using Docusign JS in our Create and embed a web form instance guide.

            Start using the new Web Forms API and updated Docusign JS library on all developer accounts today!

            Additional resources

            Gustavo Bitdinger
            Gustavo BitdingerPrincipal Product Manager

            Gustavo Bitdinger, a product innovator at Docusign since 2018, has led the launch of several products including Docusign Gen, Docusign CLM+, and most recently, Docusign Web Forms. He has a background in electrical and computer engineering and honed his skills in design thinking at the Stanford d.school. In his free time, he enjoys attending concerts, playing pub trivia, and going to the beach.

            More posts from this author

            Related posts

            • Developers

              What Are API Services? Benefits & Uses

              Docusign Contributor
            • Fast-Track Your Extension Apps with Reference Implementations

              Karissa Jacobsen
              Karissa Jacobsen
            • Paige Rossi
              Paige Rossi

            Fast-Track Your Extension Apps with Reference Implementations

            Karissa Jacobsen
            Karissa Jacobsen
            Paige Rossi
            Paige Rossi

            Discover what's new with Docusign IAM or start with eSignature for free

            Explore Docusign IAMTry eSignature for Free
            Person smiling while presenting