Web form instance processing

Web Forms API requests enable you to create and manage web form instances. These sections walk you through the processing of web form instances generated from two types of web form configuration: template-based and standalone. See Web Forms concepts for details about the differences between the two configuration types.

Instance processing: Template-based web form configuration

The next two sections illustrate how an end user, your application, and the Docusign platform interact during the processing of a web form instance generated from a template-based web form configuration.

Embedded web form instances

For this flow, the web form instance is embedded in your application, or your application redirects users to the Docusign platform to fill out the form instance.

1. A user takes an action in your application, such as clicking a button, to start filling out a form.

2. Your application launches an Instances:createInstance API request or an equivalent SDK method call to create a web form instance for the user to fill out. The request specifies the web form configuration from which to create the instance by referencing the configuration ID.

3. The response includes a secure, unique URL for the web form instance. See Web form instance URLs for details.

4. Your application renders the web form instance URL. It can do this by using the Docusign JS client SDK to embed the instance in your application, or by redirecting to the instance URL. See Render embedded web form instances for details about these options.

5. The user populates the web form instance fields and submits the instance to Docusign, which generates an envelope for the user to sign. Envelope creation and its display or delivery to the user occur automatically on web form instance submission, without requiring additional API requests from your application to create or deliver the envelope.

   The envelope includes values that the user entered on the form instance, if the form fields are connected to template fields in the web form configuration.

   The envelope delivery method depends on a setting in the web form configuration:

   • Embedded signing: If the Initiate signing session from email setting on the web form configuration signature page is not enabled, the envelope signing session is displayed in the web browser after the user submits the form.
   • Remote signing: If the Initiate signing session from email setting is enabled, the user receives an email that includes a link to the envelope signing session.
   If the web form configuration includes additional recipients who fill out the web form instance, they will receive an envelope email with a link. On selecting the link, they will be routed to the envelope with the web form instance embedded in it. After filling out the web form instance, they will be presented with the envelope. For additional recipients who are not required to fill out the web form instance, the emailed link will take them directly to the envelope.

6. Depending on the method your application used to render the form instance URL in step 4, Docusign issues one of these responses when the web form submitter signs and completes the envelope in an embedded signing session:

   1. If your application used the Docusign JS client SDK to render the form instance, Docusign returns a JavaScript sessionEnd event of type signingResult to your application when the web form submitter completes the envelope.

   2. If your application redirected the user to the form instance URL and the web form configuration is set to use embedded signing, Docusign sends the user to the returnUrl specified in the Instances:createInstance API request or equivalent SDK method call. See Redirect users after form submission for details.

      For a remote signing session, a sessionEnd event of type remoteSigningInitiated is triggered when the envelope is generated. The user is not routed to another URL upon envelope completion unless the web form template is associated with a brand that specifies a post-signing destination. See Form and envelope events and Form submission after a redirect to the Docusign platform for more information.

Remote web form instances

For this flow, users access web form instances via an envelope email.

When created from a multiple-recipient web form configuration, a remote web form instance and its associated envelope can be filled out by multiple users. Each recipient who fills out the form instance sees a distinct view with form fields specific to that user. All recipients are presented with the same envelope. The web form configuration specifies which users fill out both the form instance and envelope, and which users fill out the envelope only. The configuration also defines the order in which the recipients fill out the form instance and/or envelope. See Build a Multiple-Recipient Web Form for instructions to set up multiple recipients.

In the example illustrated here, the web form configuration specifies two recipients who complete their tasks sequentially. The example configuration also requires that both recipients populate the web form instance, as well as the envelope.

1. Your application launches an Instances:createInstance API request or an equivalent SDK method call to create a web form instance. The request specifies the web form configuration from which to create the instance by referencing the configuration ID.

   At the same time, Docusign generates an envelope based on the configuration’s web form template.

2. The first user in the routing order receives an envelope email.

3. The link in the email routes the user to the Docusign platform, which displays an envelope with an embedded web form instance. The user fills out the form fields associated with that user’s view of the web form instance. The user submits the web form instance.

   The eSignature envelope is displayed for the user to sign. Envelope display occurs automatically on web form instance submission.

   The envelope includes values that the user entered on the form instance, if the form fields are connected to template fields in the web form configuration. The user signs and completes the envelope.

4. If a brand is applied to the web form template or instance and the brand specifies a post-signing URL, the user is routed to that URL. Otherwise, the user remains on the Docusign platform.

5. The second user in the routing order receives an envelope email.

6. The link routes the user to the Docusign platform, which displays an envelope with an embedded web form instance. The user fills out the form fields associated with that user’s view of the web form instance. The user submits the web form instance.

   The eSignature envelope is displayed, and the user signs and completes it.

7. If a brand is applied to the web form template or instance and the brand specifies a post-signing URL, the user is routed to that URL. Otherwise, the user remains on the Docusign platform.

Instance processing: Standalone web form configurations

This diagram illustrates how an end user, your application, and the Docusign platform interact during the processing of a web form instance generated from a standalone web form configuration.

1. A user takes an action in your application, such as clicking a button, to start filling out a form.

2. Your application launches an Instances:createInstance API request or an equivalent SDK method call to create a web form instance for the user to fill out. The request specifies the web form configuration from which to create the instance by referencing the configuration ID.

3. The response includes a secure, unique URL for the web form instance. See Web form instance URLs for details.

4. Your application renders the web form instance URL. It can do this by using the Docusign JS client SDK to embed the instance in your application, or by redirecting to the instance URL. See Render embedded web form instances for details about these options.

5. The user populates the web form instance fields and submits the instance to Docusign.

6. Depending on the method your application used to render the form instance URL in step 4, Docusign issues one of these responses:

   1. If your application used the Docusign JS client SDK to render the form instance, Docusign returns a JavaScript sessionEnd event of type formConfirmation to your application when the user submits the web form instance.
   2. If your application redirected the user to the form instance URL, Docusign displays the thank you page defined in the web form configuration.

Next steps

• See Plan a Web Forms API integration for an overview of the implementation details that you should consider before starting work on your application.
• See the how-to guides for detailed walkthroughs and code examples.