Web Forms concepts

A web form is a web page containing fields such as text boxes, date fields, and dropdowns that users fill out to provide data that your application will collect.

The Web Forms API supports two types of web forms:

• Template-based web forms are derived from an eSignature template. After a user fills out this type of form, an envelope is generated. The user can verify or update values in the envelope and sign it.
• Standalone web forms are not associated with an eSignature template. No envelope is generated after a user fills out the web form. This type of web form is used for data collection only.

Components associated with template-based web forms

eSignature templates and envelopes are components in the creation and processing of template-based web forms. The interaction between templates, envelopes, and web forms is illustrated in this diagram:

A web form configuration defines the content and behavior of a web form. The first step in creating a template-based configuration in the Web Forms builder is selecting an eSignature template that serves as the basis for the web form configuration in two ways:

• The Web Forms builder extracts document, tab, and recipient information from the eSignature template to serve as the framework for your web form configuration, which you can edit as needed. You can create multiple web form configurations from the same template.
• A web form template is also generated when you create a web form configuration. The web form template defines the eSignature envelopes that will be generated from the form. Initially, the web form template is a copy of the original eSignature template used to create the web form configuration; however, once copied, the web form template can be modified as part of the web form configuration, independently of the eSignature template. Each web form configuration has one web form template.

After you have created and activated a web form configuration, you can create web form instances from it via Web Forms API requests. A web form instance is displayed in a browser for a user to fill out and submit. You can create unlimited web form instances from a web form configuration.

When a user submits a completed web form instance, Docusign displays an eSignature envelope for the user to sign. The envelope includes the documents and tabs defined in the web form template. In the current release, each web form instance is associated with a single envelope.

Components associated with standalone web forms

The only components associated with standalone web forms are the web form configuration, which defines the pages, fields, and validation rules for the web form, and web form instances, which are generated from the web form configuration and displayed to users in a browser.

See Create a Standalone Web Form for steps to build this type of web form configuration. You must activate the configuration before you can create web form instances from it via Web Forms API requests.

Component details

See these sections for details about web form components:

• eSignature templates
• Web form configurations
• Web form templates
• Web form instances
• eSignature envelopes

eSignature templates

An eSignature template serves as a blueprint for creating envelopes. It enables you to define recipients, documents, and tabs in a reusable format from which many envelopes can be generated. An eSignature template also serves as the basis for a template-based web form configuration and the web form template that is associated with the configuration. See Prepare a Template to Import to a Web Form for guidance on how to ensure that an eSignature template has been configured correctly for use with web forms.

Here is an example of a template definition in the Docusign eSignature web application.

Note: Standalone web form configurations are not derived from eSignature templates.

Web form configurations

Each web form has a web form configuration that defines the sequence of pages, text and fields on the pages, validation, and conditional logic. You create web form configurations in the Web Forms builder, which enables you to:

• Name the web form configuration
• Add and edit form pages
• Add and edit form fields in which users can enter data
• Set validation rules for the data that users enter
• Use conditional logic to show or hide fields and pages
• Define the content for a welcome page at the start of the web form flow and a thank you page to be displayed after users submit web form instances

A preliminary step in creating a template-based web form configuration is to select an eSignature template to provide the configuration’s framework. When the Web Forms builder generates a new web form configuration from a template, it includes:

• A web form field for each tab in the template that is one of the following types: text, attachment, checkbox, dropdown, or radio buttons
• A web form page for each document in the template that includes at least one of the tab types listed above
• A recipient for each recipient defined in the template. If the template has multiple recipients, the resulting web form configuration defines one of them as the primary recipient who fills out both the web form instance and envelope. Additional recipients can be configured to fill out both the form instance and envelope or only the envelope. For recipients who do not fill out the form instance, only their name and email address template fields are imported as web form fields, and their remaining template fields are included in the web form template. See Build a Multiple-Recipient Web Form for more information.
• A Pre-fill data page that includes any envelope custom fields defined in your account. The Pre-fill data page and its fields are not displayed to users, but you can prefill and retrieve these values via API requests for classification and reporting purposes.

Note: Attachment fields and envelope custom fields are not supported with standalone web form configurations. Attachment fields are not supported with remote web form instances.

Here is an example of a template-based web form configuration displayed in the Web Forms builder. It was derived from the eSignature template previously shown and includes a Signature step in the outline.

When you create a standalone web form configuration, the Web Forms builder generates a basic framework that includes a welcome page, a blank form page, and thank you page. You must supply the page details, including all form fields. Standalone web form configurations do not include a Signature step in the outline.

Web form templates

A web form template is an automatically generated copy of the eSignature template that was selected during creation of a template-based web form configuration. When a user completes and submits a web form instance generated from the configuration, Docusign displays an envelope created from the web form template. If the web form template has additional recipients defined, the envelope will also be sent to them.

If you want to make changes in the appearance, behavior, or distribution of envelopes generated from web form instances, you edit the web form template by accessing it through the Web Forms builder. Updates to the web form template do not change the original eSignature template from which the web form template was copied. Modifying the original eSignature template does not affect any existing web form templates that were copied from it.

Web form instances

After you’ve created a web form configuration in the Web Forms builder and activated it, you can create web form instances from that configuration via Web Forms API Instances:createInstance requests or equivalent SDK method calls. Web form instances are displayed in a browser to users, who populate the fields and submit the form instances. Web form instances may be delivered to recipients in either of two ways:

• Embedded web form instance delivery: Your Web Forms API integration embeds the web form instance in your web application or redirects the user to the Docusign platform, which displays the form instance. Each instance has a unique, secure URL. See Web form instance URLs for details.
• Remote web form instance delivery: Recipients are sent an envelope email with a link to a web form instance embedded in an envelope.

For more information about your delivery options, see When to use embedded or remote web form instance delivery.

The fields in a web form instance can be prefilled with values supplied in the API request that creates the instance. After a user has submitted a form instance, your application can retrieve the submitted field values, whether prefilled or user-populated. Here is a web form instance created from the web form configuration previously shown.

See Web form instance processing for details about how web form instances are created and presented to users.

eSignature envelopes

After a user fills out the fields in a web form instance that is displayed in a browser and submits the form instance, Docusign displays an eSignature envelope consisting of one or more documents that include values from the form instance, as well as other tabs defined in the documents, such as a signature tab. The user can review values in the envelope and sign.

The web form template that is associated with the web form configuration determines:

• Recipients in addition to the form submitter, if any, who will receive the envelope
• Documents that make up the envelope
• Tabs that appear in the documents

Web form configuration settings determine other envelope behavior, including:

• Whether the envelope is displayed in the user’s browser after form submission, known as embedded signing, or whether the user receives an emailed link to the signing page, known as remote signing
• Which form values are displayed in envelope tabs
• Whether the user can edit values that appear in envelope tabs

See The Signature Page for details about these configuration settings.

An envelope displayed on submission of the web form instance previously shown would look like this:

Next steps

• See API and UI functionality for a summary of key features and whether they are available with the API or the Web Forms builder UI.
• See Web form instance processing for an overview of the interaction between a user, a Web Forms API integration, and the Docusign platform.