Handle expirations and timeouts

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 logic should handle several different types of expiration and timeout related to web form instances:

• Instance token expiration
• Web form instance expiration
• Web form inactivity timeout
• Host website inactivity timeout

Instance token expiration

When your application creates a web form instance via an Instances:createInstance API request or equivalent SDK method call, the response includes an instance token, which is the component of a web form instance URL that makes the URL unique and secure. The instance token expires after five minutes. You cannot change this expiration period. If your application tries to load a web form instance URL that includes an expired instance token, Docusign displays this message in the browser:

To avoid the display of this message to a user, your application should check whether the instance token has expired before attempting to display the web form instance URL. The response to the Instances:createInstance request includes the instance token expiration time in the tokenExpirationDateTime property, as shown below:

{
  "id": "4b26198f-xxxx-xxxx-xxxx-50ce0cf8924a",
  "formUrl": "https://apps-d.docusign.com/webforms/us/333fdc52xxxxxxxxxxxxxxxx24c6cc03",
  "instanceToken": "U2FsdGVkX18…PzkH8v7eFQ==",
  "tokenExpirationDateTime": "2023-11-22T15:00:20.852Z",
  "clientUserId": "1234-xxxx-xxxx-efgh",
  "formId": "9e5dbf14-xxxx-xxxx-xxxx-6163f2b5401a",
  "accountId": "4b65f24e-xxxx-xxxx-xxxx-3fb0f92931d4",
  "tags": [],
  "status": "INITIATED",
  "instanceMetadata": {
    "expirationDateTime": "2024-04-20T14:55:20.852Z",
    "createdDateTime": "2023-11-22T14:55:20.852Z",
    "createdBy": {
      "userId": "a2af44c8-xxxx-xxxx-xxxx-6edb18a3168b",
      "userName": "xxxxxxxx"
    },
    "lastModifiedDateTime": "2023-11-22T14:55:20.852Z"
  }
}

If the instance token has expired, your application can obtain a new one by making an Instances:refreshToken request or equivalent SDK method call. The refresh request must include the web form instance ID returned in the id property in the response to the Instances:createInstance request. The instance token obtained via the refresh request also has a five-minute expiration, and the new expiration time appears in the tokenExpirationDateTime property in the response. You can continue to refresh instance tokens for an instance until the web form instance expires.

Refresh token after form submission to render the envelope

After a user has submitted a web form instance (the instance status is SUBMITTED), your application may need to refresh the instance token to render the envelope that was generated on form submission. The instance URL that displayed the web form instance will display the envelope after form submission if the instance token is still valid and the web form instance has not expired. This applies only if the web form instance was generated from a template-based web form configuration; instances generated from standalone web form configurations do not trigger the creation of an envelope. See Web form configuration type for more information about the two types.

Web form instance expiration

When your application creates a web form instance via an Instances:createInstance API request or equivalent SDK method call, it can set a web form instance expiration period in the expirationOffset property. This value represents the number of hours until the web form instance expires. If an expirationOffset value is not supplied, Docusign uses a default value of 720 hours (30 days). The maximum allowed expirationOffset is 23976 (999 days).

Docusign uses the expirationOffset to calculate a web form instance expiration date and time, which appear in the instanceMetadata.expirationDateTime property in the response to the Instances:createInstance request. You can also obtain the instance expiration time by making an Instances:getInstance or Instances:listInstances request or equivalent SDK method call.

How expiration affects web form instances and envelopes

After a web form instance has expired, a user can no longer access or submit the instance. In addition, for instances created from template-based web form configurations, the envelope that is generated on web form instance submission will no longer be accessible using the web form instance URL.

If your application attempts to render a web form instance URL after the instance has expired, the web form instance UI displays the message Unable to load form. To prevent this, your application should make sure that the instanceMetadata.expirationDateTime has not elapsed before attempting to render an instance URL.

If your application displays a web form instance for a user before the instanceMetadata.expirationDateTime, but the user submits the web form instance after the expiration time, the submission will fail, and the instance UI will display a Form not submitted message.

To render a web form instance for a user after the instance has expired, your application must create a new web form instance via an Instances:createInstance API request or equivalent SDK method call.

Web form instance status change at expiration time

The status of an unsubmitted web form instance changes to EXPIRED when the instanceMetadata.expirationDateTime arrives. If a user has already submitted the web form instance when the expiration time arrives, the web form instance status remains SUBMITTED and does not change to EXPIRED.

Relationship between web form instance expiration and token expiration

The relationship between the web form instance expiration and the instance token expiration is as follows:

• Instance tokens expire five minutes after they are generated. If a user attempts to access a web form instance URL containing an expired token, Docusign displays an error.
• Your application can issue Instances:refreshToken API requests or equivalent SDK method calls to obtain a new token for the web form instance until the instance expires. After that, refresh requests for the instance will result in an error response, and your application must create a new web form instance for the user.

Web form inactivity timeout

If your web application loads a web form instance in a user’s browser and the user doesn’t type or click in the form for 20 minutes, the form instance UI will time out. If your application uses the Docusign JS client SDK, it will receive a sessionEnd event of type sessionTimeout when an inactivity timeout occurs. Any data that a user entered in the web form instance prior to the timeout will be lost.

To reload the web form instance after an inactivity timeout, your application must obtain a new instance token by making an Instances:refreshToken request or equivalent SDK method call and supplying the instance ID in the request, since the instance token expiration will have elapsed. It should then use the new token to create a web form instance URL and load it.

Host website inactivity timeout

If your web application embeds web form instances in a host website, user activity in the iframe that displays the web form instance may not be detected by the host website. This may cause the host website to time the user session out for inactivity.

To avoid this, your application can use the Docusign JS client SDK to embed the web form instance and create a listener to monitor for the userActivity JavaScript event. This event is triggered when a user clicks or types in the web form instance iframe.

If the host website times a user session out before the user submits the web form instance, the iframe will close and any data that the user entered in the form will be lost. Your application can reload the form instance for the user after the user logs in to the host website again, but the application may need to refresh the instance token via an Instances:refreshToken API request or equivalent SDK method call first if the instance token expiration has elapsed.

Next steps

• See the options for rendering embedded web form instances.
• Learn about web form instance and envelope status.