> 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

# Retrieve submitted web form instance values

> Learn how your application can retrieve values submitted in a web form instance so that they can be written to a backend system.

> **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.

After a user has filled out a [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) and submitted it, your application can retrieve the form field values and write them to a backend system. See these topics for details:

* [Options to detect that a web form instance has been submitted](/docs/web-forms-api/plan-integration/retrieve-submitted-values#options-to-detect-that-a-web-form-instance-has-been-submitted)
* [Request that retrieves web form instance values](/docs/web-forms-api/plan-integration/retrieve-submitted-values#request-that-retrieves-web-form-instance-values)
* [Retrieve attachments that users upload](/docs/web-forms-api/plan-integration/retrieve-submitted-values#retrieve-attachments-that-users-upload)
* [Form instance property that identifies users](/docs/web-forms-api/plan-integration/retrieve-submitted-values#form-instance-property-that-identifies-users)

## Options to detect that a web form instance has been submitted

Your application can detect that a [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) has been submitted in two ways:

* 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 to render the web form instance, it can implement a listener for events that are triggered on form instance submission. See [Form and envelope events](/docs/web-forms-api/plan-integration/render-instances#form-and-envelope-events) for details. [How to create and embed a web form instance](/docs/web-forms-api/how-to/create-embed-web-form-instance) has listener sample code. Docusign JS only applies to embedded web form instances.
* Responses to the [Instances:getInstance](/docs/web-forms-api/reference/webforms/instances/getinstance) and [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances) API requests and equivalent [SDK](/docs/web-forms-api/sdks) method calls include a `status` property whose value will be `SUBMITTED` after a user has submitted a web form instance. The `submittedDateTime` in the `Instances:listInstances` and `Instances:getInstance` response indicates the submission date and time. See [Form instance property that identifies users](/docs/web-forms-api/plan-integration/retrieve-submitted-values#form-instance-property-that-identifies-users) for an example response.

## Request that retrieves web form instance values

Your application can retrieve a list of the form field names and values at the time of [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) submission via an [Instances:getInstance](/docs/web-forms-api/reference/webforms/instances/getinstance) API request or equivalent [SDK](/docs/web-forms-api/sdks) method call. The submitted field values appear in the `formValues` object in the response. For example:

```text
"formValues": {
  "name": "Sally Signer",
  "email": "sally.signer@email.com",
  "phone_num": {
    "countryCode": "55",
    "nationalNumber": "1133301000"
  },
  "birth_date": "1980-12-10",
  "salary": 121000,
  "marital_status": "single",
  "education": "advanced",
  "alerts": [
    "Funds_withdrawn",
    "Account_info_changed"
  ]
},
```

For form fields whose values are saved as [envelope custom fields](/docs/web-forms-api/plan-integration/retrieve-configuration-details#envelope-custom-fields), the values at the time of form instance submission are included in the `Instances:getInstance` response's `formValues` object. You can also retrieve the envelope custom field values via the eSignature API [EnvelopeCustomFields:list](/docs/esign-rest-api/reference/envelopes/envelopecustomfields/list) request or an equivalent [SDK](/docs/esign-rest-api/sdks) method call.

## Retrieve attachments that users upload

A [web form configuration](/docs/web-forms-api/web-forms-101/concepts#web-form-configurations) can include [attachment fields](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=oyz1722621351928.html) that enable users to upload files when filling out [web form instances](/docs/web-forms-api/web-forms-101/concepts#web-form-instances). The uploaded files are appended as documents to the [envelope](/docs/web-forms-api/web-forms-101/concepts#esignature-envelopes) that Docusign generates on web form instance submission.

> **Note**
>
> Attachment fields are supported with template-based web form configurations but not with standalone web form configurations or remote web form instances. See [Web form configuration type](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-type) for details.

To retrieve files uploaded in attachment fields, use these API requests or equivalent SDK method calls:

1. [Instances:getInstance](/docs/web-forms-api/reference/webforms/instances/getinstance) or [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances): Returns the envelope ID in the `envelopes` array.

   **Note:** The requests in the next two steps are [eSignature REST API](/docs/esign-rest-api) requests.
2. [EnvelopeDocuments:list](/docs/esign-rest-api/reference/envelopes/envelopedocuments/list): Returns a list of all documents in the envelope, including the files uploaded in attachment fields. In the response, you can identify files uploaded in attachment fields by the format of the `name` property, which will look like this:
   `"name": "__identification__certificate.pdf",`

   The first component of the value, which is enclosed in double underscores, is the attachment field's **API reference name** as displayed in the [Properties panel](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=wor1676501633875.html) of the Web Forms builder. This value also appears as the `componentName` in the [form field definition](/docs/web-forms-api/plan-integration/retrieve-configuration-details#form-field-definitions) in the [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) response. After the second pair of underscores, the name of the file that the user uploaded appears with a .pdf extension. All uploaded files are converted to PDF format.

   The `EnvelopeDocuments:list` response includes a document ID for each document associated with an envelope.
3. [EnvelopeDocuments:get](/docs/esign-rest-api/reference/envelopes/envelopedocuments/get): Downloads documents associated with an envelope. You can either retrieve a specific document by referencing the `documentId` returned in the `EnvelopeDocuments:list` response, or retrieve all documents in the envelope.

## Form instance property that identifies users

When you create a new [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) by making an [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) API request or equivalent [SDK](/docs/web-forms-api/sdks) method call, you supply a [clientUserId](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_clientuserid) that is a unique identifier for the user who will fill out the form instance. After form instance submission, you can use the `clientUserId` to identify the customer record in your backend system that your application will update with data collected from the form instance. The `clientUserId` appears in the responses 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 method calls. See [Identify web form instance users](/docs/web-forms-api/plan-integration/identify-instance-users) for more information.

For remote web form recipients, a `clientUserId` is not required to identify the recipient. However, it can still be useful for tracking the primary recipient associated with the web form instance. Recipients are identified by their `roleName`, which ensures the correct participant is mapped to each role in the web form.

To locate web form instances created for a specific user, use a `client_user_id` query parameter with the `Instances:listInstances` request. For example:

`https:// apps-d.docusign.com/api/webforms/v1.1/accounts/{accountId}/forms/{formId}/instances?client_user_id=1234-xxxx-xxxx-efda`

If the response includes multiple form instances with the same `clientUserId` in a `SUBMITTED` status, check the `instanceMetadata.lastModifiedDateTime` to identify the most recent form instance submission. Below is a sample portion of an `Instances:listInstances` response with two form instances submitted by the same user.

```text
{
  "id": "9fb1a4c1-xxxx-xxxx-xxxx-97b816652150",
  "clientUserId": "1234-xxxx-xxxx-efda",
  "formId": "9e5dbf14-xxxx-xxxx-xxxx-6163f2b5401a",
  "accountId": "4b65f24e-xxxx-xxxx-xxxx-3fb0f92931d4",
  "tags": [
    "tag1",
    "tag2"
  ],
  "status": "SUBMITTED",
  "instanceMetadata": {
    "expirationDateTime": "2024-05-17T15:20:12.535Z",
    "createdDateTime": "2023-12-19T15:20:12.535Z",
    "createdBy": {
      "userId": "a2af44c8-xxxx-xxxx-xxxx-6edb18a3168b",
      "userName": "xxxx"
    },
  "lastModifiedDateTime": "2023-12-19T15:20:57.446Z"
  },
  "envelopes": [
    {
        "id": "df4b9a5f-xxxx-xxxx-xxxx-2e73a296a903"
    }
  ]
},
{
  "id": "48ed96ea-xxxx-xxxx-xxxx-d2747a67c6ee",
  "clientUserId": "1234-xxxx-xxxx-efda",
  "formId": "9e5dbf14-xxxx-xxxx-xxxx-6163f2b5401a",
  "accountId": "4b65f24e-xxxx-xxxx-xxxx-3fb0f92931d4",
  "tags": [
    "tag3",
    "tag4"
  ],
  "status": "SUBMITTED",
  "instanceMetadata": {
    "expirationDateTime": "2024-01-14T06:24:15.269Z",
    "createdDateTime": "2024-01-11T18:24:15.269Z",
    "createdBy": {
      "userId": "a2af44c8-xxxx-xxxx-xxxx-6edb18a3168b",
      "userName": "xxxx"
    },
  "lastModifiedDateTime": "2024-01-11T18:25:43.615Z"
  },
  "envelopes": [
    {
        "id": "ceb7fca9-xxxx-xxxx-xxxx-76cc37c8ca98"
    }
  ]
},
```

Once you've identified a user's most recently submitted web form instance, include its `id` in an `Instances:getInstance` request to retrieve the form field values from that form instance submission.

The previous example also includes sample values for the [tags](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_tags) object, which you can populate in an `Instances:createInstance` request to associate metadata with a web form instance to help your application identify it.

## Next steps

* See [Prefill web form instance fields](/docs/web-forms-api/plan-integration/prefill-instance-fields) for information about populating a web form instance with known information about users.
* Read about your options to [redirect users after form submission](/docs/web-forms-api/plan-integration/redirect-users-form-submission).