Retrieve submitted web form instance values

After a user has filled out a web form instance 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
• Request that retrieves web form instance values
• Retrieve attachments that users upload
• 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 has been submitted in two ways:

• If your application uses the Docusign JS 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 for details. How to create and embed a web form instance has listener sample code. Docusign JS only applies to embedded web form instances.
• Responses to the Instances:getInstance and Instances:listInstances API requests and equivalent SDK 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 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 submission via an Instances:getInstance API request or equivalent SDK method call. The submitted field values appear in the formValues object in the response. For example:

"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, 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 request or an equivalent SDK method call.

Retrieve attachments that users upload

A web form configuration can include attachment fields that enable users to upload files when filling out web form instances. The uploaded files are appended as documents to the envelope that Docusign generates on web form instance submission.

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

1. Instances:getInstance or Instances:listInstances: Returns the envelope ID in the envelopes array.

   Note: The requests in the next two steps are eSignature REST API requests.

2. 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 of the Web Forms builder. This value also appears as the componentName in the form field definition in the 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: 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 by making an Instances:createInstance API request or equivalent SDK method call, you supply a 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 and Instances:listInstances requests and equivalent SDK method calls. See Identify web form 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.

{
  "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 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 for information about populating a web form instance with known information about users.
• Read about your options to redirect users after form submission.