Skip to navigation
Plan a Web Forms API integration

Render embedded web form instances

View as Markdown

The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether the Web Forms API is available for your production account plan.

Note: This topic applies only to web form instances that are embedded in a web application or displayed via a redirect to the Docusign platform. The information does not apply to remote web form instances. See When to use embedded or remote web form instance delivery for information about the delivery methods.

Your application has two options for rendering web form instances:

Regardless of which option you choose, your application must use the Web Forms API Instances:createInstance API request or an equivalent server-side SDK method call to create web form instances before rendering them.

Use Docusign JS to render web form instance URLs

Docusign JS is a JavaScript client SDK that enables you to embed web form instances in your web application. Docusign JS creates an iframe in which the web form instance is displayed and loads the web form instance URL that your application passes to it. You can access the Docusign JS libraries here:

Docusign JS features 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, if the instance was created from a template-based web form configuration. Focused view eliminates some of the Docusign signing UI components, further contributing to a seamless user experience. Focused view is not available if the web form configuration Initiate signing session from email setting is enabled.
  • Display customization options that can be set using the webFormOptions object
  • The ability to apply any CSS style property to the iframe, such as width, height, and border size
  • Form and envelope events that your application can use to trigger actions

Although it is possible to create your own iframe and embed the web form instance URL in it, Docusign recommends using Docusign JS instead. Without it, your application will not be able to take advantage of its display customization options or focused view.

webFormOptions object

The Docusign JS webFormOptions object enables you to customize the web form instance display in your web application and define other settings. The properties of webFormOptions are listed below. See How to create and embed a web form instance for sample code that includes a webFormOptions object.

PropertyTypeDefault valueDescription
autoResizeHeightbooleantrueIf true, the iframe height is adjusted automatically to display the entire form. If false, the iframe height is fixed based on the values supplied in the iframe style properties, and a vertical scrollbar appears if the form height exceeds the iframe height.
dismissWidgetOnSessionEndbooleantrueIf true, the iframe is automatically deleted when a sessionEnd event is triggered. See Form and envelope events for a list of sessionEnd event types. If false, the iframe is not deleted automatically and remains open until your web application deletes it.
hideProgressBarbooleanfalseIf true, a progress bar is not displayed at the top of the web form instance. The screenshot on Web Forms API 101 shows the progress bar. If false, the progress bar is displayed.
hideWelcomePagebooleanfalseIf true, the web form configuration welcome page is not displayed. If false, the welcome page is displayed.
instanceTokenstringAn identifier that is appended to a web form instance URL to make it unique and secure. This value is returned by the Instances:createInstance request or an equivalent server-side SDK method call.
prefillValuesa set of key/value stringsAn optional list of form fields and values with which to prefill them.
In each key/value pair, the key is the componentName from the form field definition. For dropdowns, radio buttons, and checkboxes, the values your application supplies must be allowed for the field. See Identify permitted values for dropdowns, radio buttons, and checkboxes for more information.
Below is a sample prefillValues definition that prefills the set of form fields shown in the example Instances:createInstance request in Supply prefill values in the request to create a web form instance:
text prefillValues: { name: 'Sally Signer', email: 'sally.signer@email.com', ['phone_num.countryCode']: '55', ['phone_num.nationalNumber']: '1133301000', salary: '121800.55', birth_date: '1980-12-18', marital_status: 'single', education: 'advanced', alerts: 'Funds_withdrawn,Account_info_changed' },
If form field values are supplied in the Docusign JS prefillValues property, they override prefill values supplied in the Instances:createInstance request or an equivalent server-side SDK method call. See Prefill values override web form configuration defaults for details.
showFinishLaterbooleanfalseIf true, the web form instance UI includes a Finish Later button that enables users to save a partially filled out form instance. Selecting Finish Later causes Docusign to save the form instance with any user-populated values. Docusign does not email the user a link to access the unfinished form. To enable a user to finish filling out the form, your application can render the form instance URL after refreshing the instance token, and Docusign will automatically populate the saved form values. If false, users will not have the option to save a partially filled out form instance and complete it later.
useFocusedViewForSigningbooleantrueIf true, the envelope that is generated on submission of a web form instance is presented in a focused view, which includes only the agreement to be signed and a navigation button. If false, the standard signing UI is displayed.

Form and envelope events

Docusign JS enables you to set up listeners that can receive these events. See How to create and embed a web form instance for sample code that includes listeners.

EventTypeTriggered when
readyYour web application loads a web form instance.
userActivityA user types or clicks inside the iframe that displays a web form instance.
By default, the host website in which the iframe is embedded cannot detect user actions in the iframe. This may cause the host website to time the user session out for inactivity while the user is filling out the web form instance. By monitoring this event, your application can detect user activity in the web form instance and avoid timing out the user session. See Host website inactivity timeout for additional information.
submittedA user successfully submits a completed web form instance to Docusign.
signingReadyThe envelope signing view is loaded in a user’s browser after the user submits a web form instance.
This event is triggered only if both of the following are true:
  • The web form instance was generated from a template-based web form configuration.
  • The web form configuration’s Initiate signing session from email setting is not enabled.
    This event is triggered only for the user who submits the web form instance. See Envelope status for options for tracking the status for additional envelope recipients.
sessionEndfinishLaterA web form instance submitter selects the Finish Later button after partially filling out a web form instance.
When a user selects Finish Later, the form field values are saved so that the user can resume filling out the form at another time.
sessionEndsigningResultA web form instance submitter completes or ends an envelope signing process. This event type can be triggered even if the submitter has not signed the envelope. See the section The event status parameter on the EnvelopeViews:createRecipient page for a list of completion statuses that can trigger this event.
This event is triggered only if both of the following are true:
  • The web form instance was generated from a template-based web form configuration.
  • The web form configuration’s Initiate signing session from email setting is not enabled.
    This event is triggered only for the web form instance submitter. See Envelope status for options for tracking the status for additional envelope recipients.
sessionEndremoteSigningInitiatedA user submits a web form instance, and an envelope is generated for email delivery to the user.
This event is triggered only if both of the following are true:
  • The web form instance was generated from a template-based web form configuration.
  • The web form configuration’s Initiate signing session from email setting is enabled.
    This event is triggered only for the web form instance submitter. See Envelope status for options for tracking the status for additional envelope recipients.
sessionEndformConfirmationA user submits a web form instance that was generated from a standalone web form configuration. This event is not triggered for web form instances generated from template-based web form configurations.
sessionEndsessionTimeoutDue to 20 minutes of user inactivity, a form instance session expires. See Web form inactivity timeout for details.

Redirect to web form instance URLs

For this option, your application constructs web form instance URLs and redirects users’ browsers to them. Users will see that they are being routed from your website to the Docusign platform, which displays the web form instances. See Form submission after a redirect to the Docusign platform for a description of what happens after a user submits a web form instance.

Next steps