Plan a Web Forms API integration

Before you begin work on an application that creates and manages web form instances, consider how the application will implement Web Forms API features and processes. See the table below for a list.

Note: The table indicates whether items are applicable to embedded and remote web form instance delivery. See When to use embedded or remote web form instance delivery for an overview of the differences in delivery methods.

Authenticate

Before making any Web Forms API requests, your application must obtain an access token via one of the supported OAuth 2.0 grant types: Authorization Code Grant, Implicit Grant, or JSON Web Token (JWT) Grant.

See Authentication for details.

Identify the web form configuration

When creating web form instances for users to fill out, your application must supply the ID of the web form configuration from which the instances are to be created. The web form configuration defines the form structure and the form data that will be available to your application. If the web form configuration is template-based, each web form instance has an associated envelope for the user to review and sign after form instance submission. For standalone web form configurations, envelopes are not generated. The web form configuration must be created and activated before your application can create instances from it.

See Retrieve web form configuration details for an overview of the web form configuration properties that your application can obtain via Web Forms API requests.

Identify users

Before creating a Web Forms API integration, consider which value from your backend system the integration will use to uniquely identify users who fill out web form instances. Your application can also use this value to retrieve data from your system of record and prefill form fields with known information about users, as well as write data back to the system of record.

See Identify web form instance users for details.

Customize instance and envelope appearance and behavior

Your Web Forms API integration can use the branding feature to customize the appearance and behavior of web form instances and their associated envelopes. You can create a brand in your Docusign account, define visual elements such as a logo and colors, and set behavior such as a URL to which users are routed after completing an envelope. Once you have defined a brand, you can apply it at the web form configuration level or the web form instance level.

See Apply custom branding for details.

Determine which form field values will be prefilled

The request to create a web form instance enables you to supply values that will be populated in the form fields when the web form instance loads in a user’s web browser. For instances created from template-based web form configurations, you can also prefill envelope custom fields that can be used for classification and reporting. You’ll need to determine which form field values to prefill and implement logic for setting their values. Prefilling form field values is optional.

See Prefill web form instance fields for more information.

Construct web form instance URLs

Note: This process is not applicable to remote web form instances.

If your API integration displays web form instances by embedding them in your web application or redirecting users to the Docusign platform, it must obtain the components of each instance’s secure, unique URL and combine them in the required format.

See Web form instance URLs for details.

Handle instance token and web form instance expiration

Note: This process is not applicable to remote web form instances.

When your application creates a web form instance for a user to fill out, it defines an expiration period in hours. After the expiration, users will no longer be able to submit the web form instance, and any attempt to render the instance URL will result in an error. Web form instances are also subject to a five-minute expiration for the web form instance URL instance token component, which makes the URL unique and secure. New instance tokens can be issued until a web form instance expires.

Your application should set a web form instance expiration that is appropriate for business and security needs, as well as implement instance token refresh logic to ensure that user access to a web form instance is maintained.

See Handle expirations and timeouts for more information about implementing this logic in your application.

Determine how your application renders web form instances

Note: This process is not applicable to remote web form instances.

Your application can render web form instance URLs using the Docusign JS client SDK, which embeds form instances seamlessly into your website, or by redirecting users’ browsers to the Docusign platform for the display of form instances.

See Render embedded web form instances for more information about these options.

Deliver web form instances via email

Note: This process is not applicable to embedded web form instances or instances displayed by redirecting users to the Docusign platform.

Instead of embedding web form instances or redirecting users to them, your application can trigger the sending of an envelope email with a link. The link routes a user to a web form instance that is embedded in an envelope. The user fills out the form instance and is then presented with an envelope to sign.

See Deliver remote web form instances to users for details.

Track the status of web form instances and envelopes

After your application has created web form instances, it can monitor their status. For form instances created from template-based web form configurations, your application can also track the status of the envelope that is associated with a web form instance. Monitoring the status of web form instances and envelopes enables your application to trigger additional processing as needed.

See Track web form instance and envelope status for details about the status information that is available to your application.

Retrieve form data after submission

Your application can retrieve values that a user submits in a web form instance and write them to your system of record.

See Retrieve submitted web form instance values for details about how your application can obtain these values.

Define the web page to display after form submission

After a user fills out a web form instance and submits it, your application should display an appropriate page to indicate that the user information has been received successfully.

See Redirect users after form submission for details about how your application can define a page to display.

Next steps

• See Get started with the Web Forms API for a list of requirements for making Web Forms API calls.
• See Go-Live for information about the process to move a Web Forms API integration from the developer environment to production.