> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Track web form instance and envelope status

> Learn how your Web Forms API integration can track web form instance status and the status of envelopes generated on form instance submission.

> **Note**
>
> The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact [Docusign Support](https://support.docusign.com/s/?language=en_US) 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](/docs/web-forms-api/reference/webforms/instances/createinstance) request or equivalent [SDK](/docs/web-forms-api/sdks) method call to create a new [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances), 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:

* Track [web form instance status](/docs/web-forms-api/plan-integration/track-instance-and-envelope-status#web-form-instance-status)
* Retrieve the ID of the [envelope](/docs/web-forms-api/web-forms-101/concepts#esignature-envelopes) that is associated with the web form instance, in order to track [envelope status](/docs/web-forms-api/plan-integration/track-instance-and-envelope-status#envelope-status). Envelopes are not generated for instances created from standalone configurations. See [Web form configuration type](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-type) for more information about the two types.

## Web form instance status

A [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) includes an overall [status](/docs/web-forms-api/reference/webforms/instances/createinstance#schema_200_webforminstance_webforminstance_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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=uwd1725382029336.html) 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](/docs/web-forms-api/reference/webforms/instances/createinstance#schema_200_webforminstance_webforminstance_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](/docs/web-forms-api/plan-integration/expirations-timeouts#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](/docs/web-forms-api/reference/webforms/instances/createinstance#schema_200_webforminstance_webforminstance_recipients_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](/docs/web-forms-api/reference/webforms/instances/getinstance) request, which returns information for a specific instance; an [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances) request, which returns information for all instances created from a web form configuration; or equivalent [SDK](/docs/web-forms-api/sdks) method calls.

## Envelope status

> **Note**
>
> Envelopes are generated for web form instances created from template-based web form configurations only. See [Web form configuration type](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-type) for more information.

The ID of the [envelope](/docs/web-forms-api/web-forms-101/concepts#esignature-envelopes) associated with a [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances)  appears in the `envelopes` array in the response to the [Instances:getInstance](/docs/web-forms-api/reference/webforms/instances/getinstance) and [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances) requests and equivalent [SDK](/docs/web-forms-api/sdks) method calls. For remote web form instances, the envelope is generated when the [Instances:createInstance](/docs/web-forms-api/reference/webforms/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](/docs/web-forms-api/web-forms-101/when-to-use-embedded-or-remote-delivery) for details.

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

```text
{
  "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](/docs/web-forms-api/plan-integration/render-instances#use-docusign-js-to-render-web-form-instance-urls) client SDK, your application receives JavaScript [events](/docs/web-forms-api/plan-integration/render-instances#form-and-envelope-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](/docs/web-forms-api/web-forms-101/when-to-use-embedded-or-remote-delivery).
* Use a [Docusign Connect](/platform/webhooks/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](/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges) request or an equivalent SDK method call. See [How to list envelope status changes](/docs/esign-rest-api/how-to/list-envelope-status-changes) for a walkthrough and code examples.

## Next steps

* See [Retrieve submitted web form instance values](/docs/web-forms-api/plan-integration/retrieve-submitted-values) for information about obtaining user-entered values to write to your system of record.
* [Learn about remote web form instance delivery](/docs/web-forms-api/web-forms-101/when-to-use-embedded-or-remote-delivery#learn-about-remote-web-form-instance-delivery).
* See [Redirect users after form submission](/docs/web-forms-api/plan-integration/redirect-users-form-submission) for an overview of options for routing a user to a web page after the user submits a web form instance.