Skip to navigation
Plan a Web Forms API integration

Track web form instance and envelope status

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.

When your application makes an Instances:createInstance request or equivalent SDK method call to create a new web form instance, the response includes a unique web form instance ID in the id property. The ID is a GUID. You can use this instance ID to:

Web form instance status

A web form instance includes an overall status property that reflects the current state of the form as a whole.

Valid values for status are:

  • INITIATED: The web form instance has been created but the user has not submitted it yet.
  • INPROGRESS: The user selected the Finish Later button after partially filling out a web form instance. The form field values have been saved so that the user can resume filling out the form at another time.
  • SUBMITTED: The user has filled out and submitted the web form instance.
  • EXPIRED: The instanceMetadata.expirationDateTime for the web form instance has passed without a submission, and the web form instance is no longer accessible. This status is not applicable to remote web form instances. See Web form instance expiration for more information.
  • FAILED: Instance processing failed.

Recipient status for web form instances

In addition to the overall status of a web form instance, web form instances also include an instanceRecipientStatus property. This property indicates the user’s progress towards completing their view of the web form instance.

Valid values of instanceRecipientStatus are:

  • INITIATED: The web form instance has been created for the user.
  • INPROGRESS: The user has opened the web form but has not submitted it yet. This status includes cases where the user has saved their progress to complete the web form later.
  • SUBMITTED: The user has completed and submitted their view of the web form instance.

You can retrieve both the overall web form instance status and the recipient-specific status through the response to an Instances:getInstance request, which returns information for a specific instance; an Instances:listInstances request, which returns information for all instances created from a web form configuration; or equivalent SDK method calls.

Envelope status

Envelopes are generated for web form instances created from template-based web form configurations only. See Web form configuration type for more information.

The ID of the envelope associated with a web form instance appears in the envelopes array in the response to the Instances:getInstance and Instances:listInstances requests and equivalent SDK method calls. For remote web form instances, the envelope is generated when the Instances:createInstance request is processed. For embedded web form instances, the envelope is generated when the first user submits the web form instance. See When to use embedded or remote web form instance delivery for details.

Below is an Instances:getInstance response with an envelopes array:

{
  "id": "48ed96ea-xxxx-xxxx-xxxx-d2747a67c6ee",
  "clientUserId": "1234-xxxx-xxxx-efda",
  "formId": "9e5dbf14-xxxx-xxxx-xxxx-6163f2b5401a",
  "accountId": "4b65f24e-xxxx-xxxx-xxxx-3fb0f92931d4",
  "tags": [],
  "status": "SUBMITTED",
  "instanceMetadata": {
    "expirationDateTime": "2025-08-20T06:24:15.269Z",
    "createdDateTime": "2025-08-20T18:24:15.269Z",
    "createdBy": {
      "userId": "a2af44c8-xxxx-xxxx-xxxx-6edb18a3168b",
      "userName": "xxxx"
    },
  "instanceSource": "API_REMOTE",
  "lastModifiedDateTime": "2025-08-20T18:25:43.615Z",
  "lastModifiedBy": {
       "userId": "a2af44c8-xxxx-xxxx-xxxx-6edb18a3168b",
       "userName": "xxxx"
    }
  },
  "webFormRecipients": [
    {
       "recipientViewId": "41f3109b-xxxx-xxxx-xxxx-eac994ad0988",
        "instanceRecipientStatus": "INITIATED",
        "roleName": "signer"
    }
  ],
  "envelopes": [
    {
        "id": "ceb7fca9-xxxx-xxxx-xxxx-76cc37c8ca98",
        "createdDateTime": "2025-08-20T15:57:03.653Z"
     }
  ]
}

You have several options for tracking envelope status:

  • If your application uses the Docusign JS client SDK, your application receives JavaScript events triggered by envelope activity. These events only reflect envelope activity for the web form instance submitter. To track envelopes for additional recipients, use one of the options listed below. Note that this option only applies to embedded web form instances.
  • Use a Docusign Connect listener to subscribe to receive envelope updates. When envelope status changes, Docusign Connect will send the listener an event.
  • Use the eSignature Envelopes:listStatusChanges request or an equivalent SDK method call. See How to list envelope status changes for a walkthrough and code examples.

Next steps