Skip to navigation
Plan a Web Forms API integration

Web form instance URLs

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.

When your application creates a web form instance via an Instances:createInstance request or equivalent SDK method call, Docusign returns values that your application can use to create a unique, secure URL to display the web form instance in a user’s browser.

The components of the instance URL in the Instances:createInstance response are:

  • formUrl: The base instance URL for the web form configuration. This is the same for all web form instances created from the configuration.
  • instanceToken: A value that is unique to a user’s form session. The token protects the data in the web form instance and ensures that the user only fills the form out once per session. As an additional security measure, web form instance tokens expire five minutes after they are generated. See Instance token expiration for details.

To construct a web form instance URL, your application must append the instanceToken value to the formUrl value in this format:

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

For example:

https://apps-d.docusign.com/webforms/us/``333fdc52xxxxxxxxxxxxxxxx24c6cc03#instanceToken=U2FsdGVkxxxxxxxxxxxxxxxxqgmZHxw=

The Docusign JS client SDK library automatically constructs web form instance URLs from these components. See How to create and embed a web form instance for code examples.

Instance URL after form submission

For web form instances created from template-based web form configurations, your application can still render the form instance URL even after a user has completed the form instance and the instance status is SUBMITTED. In this case, the following occurs:

  • If the user has not completed the envelope that was generated on form instance submission, the envelope signing view is displayed, and the user can sign the envelope.
  • If the user has completed the envelope, a read-only copy of the envelope is displayed.
  • If the web form instance has expired, the web form instance UI displays an Unable to load form message, regardless of whether or not the user has completed the envelope.

For web form instances created from standalone web form configurations, your application should not attempt to render the form instance URL after submission. If it does so, the web form instance UI displays the message Unable to load form.

See Web form configuration type for more information about template-based and standalone web form configurations.

Next steps